Improved plugin api documentation

docs/docs/plugin-api.rst

@@ -19,19 +19,19 @@ API Interface
 ~~~~~~~~~~~~~
 
 .. automodule:: api
-    :undoc-members:
 
 
 API Return Classes
 ~~~~~~~~~~~~~~~~~~
 
 .. automodule:: api_classes
-    :undoc-members:
 
-Jedi setting interface
+Settings Module
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~
 
 .. automodule:: settings
+    :no-members:
+    :no-undoc-members:
 
 Examples
 --------

docs/index.rst

@@ -6,8 +6,6 @@ Jedi
 Release v\ |release|. (:doc:`Installation <docs/installation>`)
 
 .. automodule:: jedi
-    :members:
-    :undoc-members:
 
 Autocompletion can look like this (e.g. VIM plugin):
 

jedi/api.py

@@ -1,9 +1,10 @@
 """
-The api basically only provides one class. You can create a :class:`Script` and
+The API basically only provides one class. You can create a :class:`Script` and
-use it's ``complete`` / ``goto`` / etc functions.
+use its methods.
+
 Additionally you can add a debug function with :func:`set_debug_function` and
-catch :exc:`NotFoundError` which is being raised if your completion is
+catch :exc:`NotFoundError` which is being raised if your completion is not
-impossible.
+possible.
 """
 from __future__ import with_statement
 __all__ = ['Script', 'NotFoundError', 'set_debug_function']
@@ -35,7 +36,7 @@ class NotFoundError(Exception):
 class Script(object):
     """
     A Script is the base for a completion, goto or whatever you want to do with
-    jedi.
+    |jedi|.
 
     :param source: The source code of the current file, separated by newlines.
     :type source: string
@@ -71,7 +72,7 @@ class Script(object):
         Return :class:`api_classes.Completion` objects. Those objects contain
         information about the completions, more than just names.
 
-        :return: completion objects, sorted by name and __ comes last.
+        :return: Completion objects, sorted by name and __ comes last.
         :rtype: list of :class:`api_classes.Completion`
         """
         def follow_imports_if_possible(name):

jedi/api_classes.py

@@ -1,6 +1,7 @@
-"""`api_classes` contains the return classes of the API. These classes are the
+"""
-much bigger part of the whole API, because here you get out the information
+The :mod:`api_classes` module contains the return classes of the API. These
-about completion and goto operations.
+classes are the much bigger part of the whole API, because they contain the
+interesting information about completion and goto operations.
 """
 
 import re
@@ -20,7 +21,7 @@ import keywords
 
 def _clear_caches():
     """
-    Clears all caches of this and related modules. The only cache that will not
+    Clear all caches of this and related modules. The only cache that will not
     be deleted is the module cache.
     """
     cache.clear_caches()
@@ -231,7 +232,7 @@ class Completion(BaseDefinition):
     def follow_definition(self):
         """
         Return the original definitions. I strongly recommend not using it for
-        your completions, because it might slow down *Jedi*. If you want to read
+        your completions, because it might slow down |jedi|. If you want to read
         only a few objects (<=20), it might be useful, especially to
         get the original docstrings. The basic problem of this function is
         that it follows all results. This means with 1000 completions (e.g.

jedi/settings.py

@@ -1,60 +1,77 @@
 """
-Variables to hold global jedi setting.
+This module contains variables with global |jedi| setting. To change the
+behavior of |jedi|, change the variables defined in
+:mod:`jedi.settings`.
 
-Plugin can change the variables defined in :mod:`jedi.settings` to
+Plugins should expose an interface so that the user can adjust the
-modify behavior of Jedi.  Plugin should expose an interface to setup
+configuration.
-these variables by user.  Example usage::
+
+
+Example usage::
 
     from jedi import settings
     settings.case_insensitive_completion = True
 
-* Completion output settings
 
-  - :data:`case_insensitive_completion`
+Completion output
-  - :data:`add_dot_after_module`
+~~~~~~~~~~~~~~~~~
-  - :data:`add_bracket_after_function`
-  - :data:`no_completion_duplicates`
 
-* Parser
+.. autodata:: case_insensitive_completion
+.. autodata:: add_dot_after_module
+.. autodata:: add_bracket_after_function
+.. autodata:: no_completion_duplicates
 
-  - :data:`fast_parser`
-  - :data:`fast_parser_always_reparse`
-  - :data:`use_get_in_function_call_cache`
 
-* Dynamic stuff
+Parser
+~~~~~~
 
-  - :data:`dynamic_arrays_instances`
+.. autodata:: fast_parser
-  - :data:`dynamic_array_additions`
+.. autodata:: fast_parser_always_reparse
-  - :data:`dynamic_params`
+.. autodata:: use_get_in_function_call_cache
-  - :data:`dynamic_params_for_other_modules`
-  - :data:`additional_dynamic_modules`
 
-* Recursions
 
-  Recursion settings are important if you don't want extremly
+Dynamic stuff
-  recursive python code to go absolutely crazy. First of there is a
+~~~~~~~~~~~~~
-  global limit :data:`max_executions`. This limit is important, to set
-  a maximum amount of time, the completion may use.
 
-  The values are based on my experimental tries, used on the jedi library. But
+.. autodata:: dynamic_arrays_instances
-  I don't think there's any other Python library, that uses recursion in a
+.. autodata:: dynamic_array_additions
-  similar (extreme) way. This makes the completion definitely worse in some
+.. autodata:: dynamic_params
-  cases. But a completion should also be fast.
+.. autodata:: dynamic_params_for_other_modules
+.. autodata:: additional_dynamic_modules
 
-  - :data:`max_until_execution_unique`
-  - :data:`max_function_recursion_level`
-  - :data:`max_executions_without_builtins`
-  - :data:`max_executions`
-  - :data:`scale_get_in_function_call`
 
-* Various
+Recursions
+~~~~~~~~~~
 
-  - :data:`part_line_length`
+Recursion settings are important if you don't want extremly
+recursive python code to go absolutely crazy. First of there is a
+global limit :data:`max_executions`. This limit is important, to set
+a maximum amount of time, the completion may use.
 
-* Caching validity (time)
+The default values are based on experiments while completing the |jedi| library
+itself (inception!). But I don't think there's any other Python library that
+uses recursion in a similarly extreme way. These settings make the completion
+definitely worse in some cases. But a completion should also be fast.
+
+.. autodata:: max_until_execution_unique
+.. autodata:: max_function_recursion_level
+.. autodata:: max_executions_without_builtins
+.. autodata:: max_executions
+.. autodata:: scale_get_in_function_call
+
+
+Caching
+~~~~~~~
+
+.. autodata:: star_import_cache_validity
+.. autodata:: get_in_function_call_validity
+
+
+Various
+~~~~~~~
+
+.. autodata:: part_line_length
 
-  - :data:`star_import_cache_validity`
-  - :data:`get_in_function_call_validity`
 
 """
 
@@ -116,7 +133,7 @@ The goal is to move away from it by making the rest faster.
 
 dynamic_arrays_instances = True
 """
-check for `append`, etc. on array instances like list()
+Check for `append`, etc. on array instances like list()
 """
 
 dynamic_array_additions = True
@@ -137,8 +154,8 @@ Do the same for other modules.
 
 additional_dynamic_modules = []
 """
-Additional modules in which Jedi checks if statements are to be found. This
+Additional modules in which |jedi| checks if statements are to be found. This
-is practical for IDE's, that want to administrate their modules themselves.
+is practical for IDEs, that want to administrate their modules themselves.
 """
 
 # ----------------
@@ -147,10 +164,10 @@ is practical for IDE's, that want to administrate their modules themselves.
 
 max_until_execution_unique = 50
 """
-The `max_until_execution_unique` limit is probably the most important one,
+This limit is probably the most important one, because if this limit is
-because if that limit is passed, functions can only be one time executed. So
+exceeded, functions can only be one time executed. So new functions will be
-new functions will be executed, complex recursions with the same functions
+executed, complex recursions with the same functions again and again, are
-again and again, are ignored.
+ignored.
 """
 
 max_function_recursion_level = 5