Started creating full documentation

docs/source/conf.py

@@ -17,6 +17,7 @@ import sys, os
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../../jedi'))
 
 # -- General configuration -----------------------------------------------------
 

docs/source/index.rst

@@ -3,10 +3,18 @@ Jedi – Python autocompletion that works!
 
 
 .. automodule:: jedi
+    :members:
+    :undoc-members:
 
 
+Contents
+========
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   installation
+   plugin-api
 
 
 Indices and tables
@@ -15,4 +23,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/source/installation.rst

@@ -0,0 +1,45 @@
+Installation and Configuration
+==============================
+
+You can either include *Jedi* as a submodule in your text editor plugin (like
+jedi-vim_ does it by default), or you can install it systemwide.
+
+
+System-wide installation via a package manager
+----------------------------------------------
+
+You can install *Jedi* directly from pypi using pip::
+
+    sudo pip install jedi
+
+If you want to install the current development version::
+
+    sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi
+
+.. note:: This just installs the Jedi library, not the editor plugins. For
+    information about how to make it work with your editor, refer to the
+    corresponding documentation.
+
+
+Manual installation from a downloaded package
+---------------------------------------------
+
+If you prefer not to use an automated package installer, you can download a
+copy of *Jedi* and install it manually.
+
+To install it, navigate to the directory containing `setup.py` on your console
+and type::
+
+    sudo python setup.py install
+
+
+Inclusion as a submodule
+------------------------
+
+If you use an editor plugin like jedi-vim_, you can simply include *Jedi* as a
+git submodule of the plugin directory. Vim plugin managers like Vundle_ make it
+very easy to keep submodules up to date.
+
+
+.. _jedi-vim: https://github.com/davidhalter/jedi-vim
+.. _Vundle: https://github.com/gmarik/vundle

docs/source/plugin-api.rst

@@ -0,0 +1,54 @@
+The plugin API
+==============
+
+.. currentmodule:: jedi
+
+If you want to set up an editor/IDE-plugin with **Jedi**, you first need to
+``import jedi``. You then have direct access to the :class:`.Script`,
+:class:`.NotFoundError` and :func:`.set_debug_function` objects.
+
+
+API documentation
+-----------------
+
+Main class
+~~~~~~~~~~
+
+.. module:: api
+
+.. autoclass:: Script
+    :members:
+
+API Classes
+~~~~~~~~~~~
+
+.. module:: api_classes
+
+.. autoclass:: Completion
+    :members:
+
+.. autoclass:: Definition
+    :members:
+
+.. autoclass:: RelatedName
+    :members:
+
+Exceptions
+~~~~~~~~~~
+
+.. module:: api
+
+.. autoexception:: NotFoundError
+
+Useful functions
+~~~~~~~~~~~~~~~~
+
+.. module:: api
+
+.. autofunction:: set_debug_function
+
+
+Examples
+--------
+
+TODO

jedi/api.py

@@ -53,16 +53,17 @@ class Script(object):
     """
     A Script is the base for a completion, goto or whatever call.
 
-    :param source: The source code of the current file
+    :param source: The source code of the current file, separated by newlines.
     :type source: string
-    :param line: The line to complete in.
+    :param line: The line to perform actions on (starting with 1).
     :type line: int
-    :param col: The column to complete in.
+    :param col: The column of the cursor (starting with 0).
     :type col: int
-    :param source_path: The path in the os, the current module is in.
+    :param source_path: The path of the file in the file system, or ``None`` if
+        it hasn't been saved yet.
     :type source_path: string or None
-    :param source_encoding: encoding for decoding `source`, if it
+    :param source_encoding: The encoding of ``source``, if it is not a
-                            is not a `unicode` object.
+        ``unicode`` object (default `utf-8`).
     :type source_encoding: string
     """
     def __init__(self, source, line, column, source_path,
@@ -82,9 +83,11 @@ class Script(object):
 
     def complete(self):
         """
-        An auto completer for python files.
+        Return :class:`api_classes.Completion` objects. Those objects contain
+        information about the completions, more than just names.
 
-        :return: list of Completion objects, sorted by name and __ comes last.
+        :return: list of :class:`api_classes.Completion` objects, sorted by
+            name and __ comes last.
         :rtype: list
         """
         def follow_imports_if_possible(name):
@@ -205,16 +208,16 @@ class Script(object):
 
     def get_definition(self):
         """
-        Returns the definitions of a the path under the cursor. This is
+        Return the definitions of a the path under the cursor. This is not a
-        not a goto function! This follows complicated paths and returns the
+        goto function! This follows complicated paths and returns the end, not
-        end, not the first definition.
+        the first definition. The big difference of :meth:`goto` and
-        The big difference of goto and get_definition is that goto doesn't
+        :meth:`get_definition` is that :meth:`goto` doesn't follow imports and
-        follow imports and statements.
+        statements. Multiple objects may be returned, because Python itself is
-        Multiple objects may be returned, because Python itself is a dynamic
+        a dynamic language, which means depending on an option you can have two
-        language, which means depending on an option you can have two different
+        different versions of a function.
-        versions of a function.
 
-        :return: list of Definition objects, which are basically scopes.
+        :return: list of :class:`api_classes.Definition` objects, which are
+            basically scopes.
         :rtype: list
         """
         def resolve_import_paths(scopes):
@@ -246,13 +249,13 @@ class Script(object):
 
     def goto(self):
         """
-        Returns the first definition found by goto. This means: It doesn't
+        Return the first definition found by goto. Imports and statements
-        follow imports and statements.
+        aren't followed.  Multiple objects may be returned, because Python
-        Multiple objects may be returned, because Python itself is a dynamic
+        itself is a dynamic language, which means depending on an option you
-        language, which means depending on an option you can have two different
+        can have two different versions of a function.
-        versions of a function.
 
-        :return: list of Definition objects, which are basically scopes.
+        :return: list of :class:`api_classes.Definition` objects, which are
+            basically scopes.
         """
         d = [api_classes.Definition(d) for d in set(self._goto()[0])]
         return sorted(d, key=lambda x: (x.module_path, x.start_pos))
@@ -303,10 +306,10 @@ class Script(object):
 
     def related_names(self, additional_module_paths=[]):
         """
-        Returns `dynamic.RelatedName` objects, which contain all names, that
+        Return :class:`api_classes.RelatedName` objects, which contain all
-        are defined by the same variable, function, class or import.
+        names that point to the definition of the name under the cursor. This
-        This function can be used either to show all the usages of a variable
+        is very useful for refactoring (renaming), or to show all usages of a
-        or for renaming purposes.
+        variable.
 
         TODO implement additional_module_paths
         """
@@ -446,7 +449,8 @@ class Script(object):
 def set_debug_function(func_cb=debug.print_to_stdout, warnings=True,
                                             notices=True, speed=True):
     """
-    You can define a callback debug function to get all the debug messages.
+    Define a callback debug function to get all the debug messages.
+
     :param func_cb: The callback function for debug messages, with n params.
     """
     debug.debug_function = func_cb

jedi/api_classes.py

@@ -266,6 +266,7 @@ class Definition(BaseDefinition):
 
 
 class RelatedName(BaseDefinition):
+    """TODO: document this"""
     def __init__(self, name_part, scope):
         super(RelatedName, self).__init__(scope, name_part.start_pos)
         self.name_part = name_part