diff --git a/docs/source/conf.py b/docs/source/conf.py index 0135c894..e078321e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,7 +26,7 @@ sys.path.insert(0, os.path.abspath('../../jedi')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -241,3 +241,7 @@ texinfo_documents = [ # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' + +# -- Options for todo module --------------------------------------------------- + +todo_include_todos = False diff --git a/jedi/api.py b/jedi/api.py index 46ee3824..1ec179f3 100644 --- a/jedi/api.py +++ b/jedi/api.py @@ -45,7 +45,7 @@ from _compatibility import next, unicode class NotFoundError(Exception): - """ A custom error to avoid catching the wrong exceptions """ + """A custom error to avoid catching the wrong exceptions.""" pass @@ -78,7 +78,7 @@ class Script(object): @property def parser(self): - """ The lazy parser """ + """ The lazy parser.""" return self.module.parser def complete(self): @@ -210,7 +210,7 @@ class Script(object): """ Return the definitions of a the path under the cursor. This is not a goto function! This follows complicated paths and returns the end, not - the first definition. The big difference of :meth:`goto` and + the first definition. The big difference between :meth:`goto` and :meth:`get_definition` is that :meth:`goto` doesn't follow imports and statements. Multiple objects may be returned, because Python itself is a dynamic language, which means depending on an option you can have two @@ -311,7 +311,7 @@ class Script(object): is very useful for refactoring (renaming), or to show all usages of a variable. - TODO implement additional_module_paths + .. todo:: Implement additional_module_paths """ user_stmt = self.parser.user_stmt definitions, search_name = self._goto(add_import_name=True) @@ -340,13 +340,17 @@ class Script(object): def get_in_function_call(self): """ - Return the function, that the cursor is in, e.g.: - >>> isinstance(| # | <-- cursor is here + Return the function object of the call you're currently in. + + E.g. if the cursor is here:: - This would return the `isinstance` function. In contrary: - >>> isinstance()| # | <-- cursor is here + >>> abs(# <-- cursor is here - This would return `None`. + This would return the ``abs`` function. On the other hand:: + + >>> abs()# <-- cursor is here + + This would return ``None``. """ def check_user_stmt(user_stmt): if user_stmt is None \ diff --git a/jedi/api_classes.py b/jedi/api_classes.py index e407efc8..7e490591 100644 --- a/jedi/api_classes.py +++ b/jedi/api_classes.py @@ -135,8 +135,10 @@ class BaseDefinition(object): class Completion(BaseDefinition): - """ `Completion` objects are returned from `Script.complete`. Providing - some useful functions for IDE's. """ + """ + `Completion` objects are returned from :meth:`api.Script.complete`. They + provide additional information about a completion. + """ def __init__(self, name, needs_dot, like_name_length, base): super(Completion, self).__init__(name.parent, name.start_pos) @@ -149,11 +151,13 @@ class Completion(BaseDefinition): @property def complete(self): - """ Delievers the rest of the word, e.g. completing `isinstance` - >>> isinstan + """ + Return the rest of the word, e.g. completing ``isinstance``:: + + >>> isinstan# <-- Cursor is here would return the string 'ce'. It also adds additional stuff, depending - on your `settings.py` + on your `settings.py`. """ dot = '.' if self.needs_dot else '' append = '' @@ -170,8 +174,10 @@ class Completion(BaseDefinition): @property def word(self): - """ In contrary to `complete` returns the whole word, e.g. - >>> isinstan + """ + Similar to :meth:`Completion.complete`, but return the whole word, e.g. :: + + >>> isinstan would return 'isinstance'. """ @@ -179,8 +185,11 @@ class Completion(BaseDefinition): @property def description(self): - """ Provides a description of the completion object - TODO return value is just __repr__ of some objects, improve! """ + """ + Provide a description of the completion object. + + .. todo:: return value is just __repr__ of some objects, improve! + """ parent = self.name.parent if parent is None: return '' @@ -194,12 +203,13 @@ class Completion(BaseDefinition): return '%s: %s%s' % (t, desc, line_nr) def follow_definition(self): - """ Returns you the original definitions. I strongly recommend not - using it for your completions, because it might slow down Jedi. If you - want to read only a few objects (<=20). I think 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. numpy), it's just PITA slow. + """ + Return the original definitions. I strongly recommend not using it for + 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. + numpy), it's just PITA-slow. """ if self._followed_definitions is None: if self.definition.isinstance(parsing.Statement): @@ -220,15 +230,19 @@ class Completion(BaseDefinition): class Definition(BaseDefinition): - """ These are the objects returned by either `Script.goto` or - `Script.get_definition`. """ + """ + *Definition* objects are returned from :meth:`api.Script.goto` or + :meth:`api.Script.get_definition`. + """ def __init__(self, definition): super(Definition, self).__init__(definition, definition.start_pos) @property def description(self): - """ A description of the Definition object, which is heavily used in - testing. e.g. for `isinstance` it returns 'def isinstance' """ + """ + A description of the :class:`.Definition` object, which is heavily used + in testing. e.g. for ``isinstance`` it returns ``def isinstance``. + """ d = self.definition if isinstance(d, evaluate.InstanceElement): d = d.var @@ -252,10 +266,15 @@ class Definition(BaseDefinition): @property def desc_with_module(self): - """ In addition to the Definition, it also returns the module. Don't - use it yet, its behaviour may change. If you really need it, talk to me - TODO add full path. This function is should return a - module.class.function path. """ + """ + In addition to the definition, also return the module. + + .. warning:: Don't use this function yet, its behaviour may change. If + you really need it, talk to me. + + .. todo:: Add full path. This function is should return a + `module.class.function` path. + """ if self.module_path.endswith('.py') \ and not isinstance(self.definition, parsing.Module): position = '@%s' % (self.line_nr)