Merge branch 'docs' of https://github.com/blueyed/jedi into refactor

Almost all of the docstrings were still there.

docs/conf.py

@@ -13,7 +13,6 @@
 
 import sys
 import os
-import datetime
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -145,7 +144,7 @@ html_sidebars = {
         #'relations.html',
         'ghbuttons.html',
         #'sourcelink.html',
-        #'searchbox.html'
+        'searchbox.html'
     ]
 }
 
@@ -274,7 +273,8 @@ autodoc_default_flags = []
 # -- Options for intersphinx module --------------------------------------------
 
 intersphinx_mapping = {
-    'https://docs.python.org/': None,
+    'python': ('https://docs.python.org/', None),
+    'parso': ('https://parso.readthedocs.io/en/latest/', None),
 }
 
 

docs/docs/development.rst

@@ -59,11 +59,11 @@ because that's where all the magic happens. I need to introduce the :ref:`parser
 Parser
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Jedi used to have it's internal parser, however this is now a separate project
+Jedi used to have its internal parser, however this is now a separate project
 and is called `parso <http://parso.readthedocs.io>`_.
 
 The parser creates a syntax tree that |jedi| analyses and tries to understand.
-The grammar that this parsers uses is very similar to the official Python
+The grammar that this parser uses is very similar to the official Python
 `grammar files <https://docs.python.org/3/reference/grammar.html>`_.
 
 .. _inference:

jedi/api/__init__.py

@@ -75,12 +75,8 @@ class Script(object):
 
     - if `sys_path` parameter is not ``None``, it will be used as ``sys.path``
       for the script;
-
-    - if `sys_path` parameter is ``None`` and ``VIRTUAL_ENV`` environment
-      variable is defined, ``sys.path`` for the specified environment will be
-      guessed (see :func:`jedi.inference.sys_path.get_venv_path`) and used for
-      the script;
-
+    - if `environment` is provided, its ``sys.path`` will be used
+      (see :func:`Environment.get_sys_path <jedi.api.environment.Environment.get_sys_path>`);
     - otherwise ``sys.path`` will match that of |jedi|.
 
     :param source: The source code of the current file, separated by newlines.
@@ -208,13 +204,15 @@ class Script(object):
     @validate_line_column
     def complete(self, line=None, column=None, **kwargs):
         """
-        Return :class:`classes.Completion` objects. Those objects contain
-        information about the completions, more than just names.
+        Return :class:`.Completion` objects.
+
+        Those objects contain information about the completions, more than just
+        names.
 
         :param fuzzy: Default False. Will return fuzzy completions, which means
             that e.g. ``ooa`` will match ``foobar``.
-        :return: Completion objects, sorted by name and ``__`` comes last.
-        :rtype: list of :class:`classes.Completion`
+        :return: Completion objects, sorted by name and __ comes last.
+        :rtype: list of :class:`.Completion`
         """
         return self._complete(line, column, **kwargs)
 
@@ -244,7 +242,7 @@ class Script(object):
         :param only_stubs: Only return stubs for this goto call.
         :param prefer_stubs: Prefer stubs to Python objects for this type
             inference call.
-        :rtype: list of :class:`classes.Definition`
+        :rtype: list of :class:`.Definition`
         """
         with debug.increase_indent_cm('infer'):
             return self._infer(line, column, **kwargs)
@@ -288,15 +286,15 @@ class Script(object):
         """
         Return the first definition found, while optionally following imports.
         Multiple objects may be returned, because Python itself is a
-        dynamic language, which means you can have two different versions of a
-        function.
+        dynamic language, which means depending on an option you can have two
+        different versions of a function.
 
         :param follow_imports: The goto call will follow imports.
         :param follow_builtin_imports: If follow_imports is True will try to
             look up names in builtins (i.e. compiled or extension modules).
         :param only_stubs: Only return stubs for this goto call.
         :param prefer_stubs: Prefer stubs to Python objects for this goto call.
-        :rtype: list of :class:`classes.Definition`
+        :rtype: list of :class:`.Definition`
         """
         with debug.increase_indent_cm('goto'):
             return self._goto(line, column, **kwargs)
@@ -398,14 +396,14 @@ class Script(object):
     @validate_line_column
     def get_references(self, line=None, column=None, **kwargs):
         """
-        Return :class:`classes.Definition` objects, which contain all
+        Return :class:`.Definition` objects, which contain all
         names that point to the definition of the name under the cursor. This
         is very useful for refactoring (renaming), or to show all references of
         a variable.
 
         :param include_builtins: Default True, checks if a reference is a
             builtin (e.g. ``sys``) and in that case does not return it.
-        :rtype: list of :class:`classes.Definition`
+        :rtype: list of :class:`.Definition`
         """
 
         def _references(include_builtins=True):
@@ -441,7 +439,7 @@ class Script(object):
 
         This would return an empty list..
 
-        :rtype: list of :class:`classes.Signature`
+        :rtype: list of :class:`.CallSignature`
         """
         pos = line, column
         call_details = helpers.get_signature_details(self._module_node, pos)

jedi/api/classes.py

@@ -415,8 +415,9 @@ class BaseDefinition(object):
         """
         Deprecated! Will raise a warning soon. Use get_signatures()[...].params.
 
-        Raises an ``AttributeError`` if the definition is not callable.
-        Otherwise returns a list of `Definition` that represents the params.
+        Raises :exc:`AttributeError` if the definition is not callable.
+        Otherwise returns a list of :class:`.Definition` that represents the
+        params.
         """
         warnings.warn(
             "Deprecated since version 0.16.0. Use get_signatures()[...].params",

jedi/api/environment.py

@@ -91,8 +91,8 @@ class Environment(_BaseEnvironment):
         """
         self.version_info = _VersionInfo(*info[2])
         """
-        Like ``sys.version_info``. A tuple to show the current Environment's
-        Python version.
+        Like :data:`sys.version_info`: a tuple to show the current
+        Environment's Python version.
         """
 
         # py2 sends bytes via pickle apparently?!
@@ -117,7 +117,7 @@ class Environment(_BaseEnvironment):
     def get_sys_path(self):
         """
         The sys path for this environment. Does not include potential
-        modifications like ``sys.path.append``.
+        modifications from e.g. appending to :data:`sys.path`.
 
         :returns: list of str
         """
@@ -185,7 +185,7 @@ def get_default_environment():
     makes it possible to use as many new Python features as possible when using
     autocompletion and other functionality.
 
-    :returns: :class:`Environment`
+    :returns: :class:`.Environment`
     """
     virtual_env = _get_virtual_env_from_var()
     if virtual_env is not None:
@@ -272,7 +272,7 @@ def find_virtualenvs(paths=None, **kwargs):
         CONDA_PREFIX will be checked to see if it contains a valid conda
         environment.
 
-    :yields: :class:`Environment`
+    :yields: :class:`.Environment`
     """
     def py27_comp(paths=None, safe=True, use_environment_vars=True):
         if paths is None:
@@ -322,7 +322,7 @@ def find_system_environments():
 
     The environments are sorted from latest to oldest Python version.
 
-    :yields: :class:`Environment`
+    :yields: :class:`.Environment`
     """
     for version_string in _SUPPORTED_PYTHONS:
         try:
@@ -339,7 +339,7 @@ def get_system_environment(version):
     where X and Y are the major and minor versions of Python.
 
     :raises: :exc:`.InvalidPythonEnvironment`
-    :returns: :class:`Environment`
+    :returns: :class:`.Environment`
     """
     exe = which('python' + version)
     if exe:

jedi/inference/compiled/value.py

@@ -21,7 +21,7 @@ from jedi.inference.context import CompiledContext, CompiledModuleContext
 
 
 class CheckAttribute(object):
-    """Raises an AttributeError if the attribute X isn't available."""
+    """Raises :exc:`AttributeError` if the attribute X is not available."""
     def __init__(self, check_name=None):
         # Remove the py in front of e.g. py__call__.
         self.check_name = check_name

jedi/inference/recursion.py

@@ -3,8 +3,8 @@ Recursions are the recipe of |jedi| to conquer Python code. However, someone
 must stop recursions going mad. Some settings are here to make |jedi| stop at
 the right time. You can read more about them :ref:`here <settings-recursion>`.
 
-Next to :mod:`jedi.inference.cache` this module also makes |jedi| not
-thread-safe. Why?  ``execution_recursion_decorator`` uses class variables to
+Next to the internal ``jedi.inference.cache`` this module also makes |jedi| not
+thread-safe, because ``execution_recursion_decorator`` uses class variables to
 count the function calls.
 
 .. _settings-recursion:
@@ -34,7 +34,7 @@ from jedi.inference.base_value import NO_VALUES
 
 recursion_limit = 15
 """
-Like ``sys.getrecursionlimit()``, just for |jedi|.
+Like :func:`sys.getrecursionlimit()`, just for |jedi|.
 """
 total_function_execution_limit = 200
 """