docs: fix some incorrect reference and improve wording

jedi/api/__init__.py

@@ -55,10 +55,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.evaluate.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|.
 
@@ -160,11 +158,13 @@ class Script(object):
 
     def completions(self):
         """
-        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.
 
         :return: Completion objects, sorted by name and __ comes last.
-        :rtype: list of :class:`classes.Completion`
+        :rtype: list of :class:`.Completion`
         """
         debug.speed('completions start')
         completion = Completion(
@@ -185,7 +185,7 @@ class Script(object):
         because Python itself is a dynamic language, which means depending on
         an option you can have two different versions of a function.
 
-        :rtype: list of :class:`classes.Definition`
+        :rtype: list of :class:`.Definition`
         """
         leaf = self._module_node.get_name_of_position(self._pos)
         if leaf is None:
@@ -210,7 +210,7 @@ class Script(object):
         dynamic language, which means depending on an option you can have two
         different versions of a function.
 
-        :rtype: list of :class:`classes.Definition`
+        :rtype: list of :class:`.Definition`
         """
         def filter_follow_imports(names, check):
             for name in names:
@@ -240,14 +240,14 @@ class Script(object):
 
     def usages(self, additional_module_paths=()):
         """
-        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 usages of a
         variable.
 
         .. todo:: Implement additional_module_paths
 
-        :rtype: list of :class:`classes.Definition`
+        :rtype: list of :class:`.Definition`
         """
         tree_name = self._module_node.get_name_of_position(self._pos)
         if tree_name is None:
@@ -273,7 +273,7 @@ class Script(object):
 
         This would return an empty list..
 
-        :rtype: list of :class:`classes.CallSignature`
+        :rtype: list of :class:`.CallSignature`
         """
         call_signature_details = \
             helpers.get_call_signature_details(self._module_node, self._pos)

jedi/api/classes.py

@@ -311,8 +311,9 @@ class BaseDefinition(object):
     @memoize_method
     def params(self):
         """
-        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.
         """
         def get_param_names(context):
             param_names = []

jedi/api/environment.py

@@ -64,8 +64,8 @@ class Environment(_BaseEnvironment):
         self.version_info = self._get_version()
         """
 
-        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.
         """
 
     def _get_version(self):
@@ -104,7 +104,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
         """
@@ -162,7 +162,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:
@@ -193,7 +193,7 @@ def find_virtualenvs(paths=None, **kwargs):
         default. If the executable has not been installed by root, it will not
         be executed.
 
-    :yields: :class:`Environment`
+    :yields: :class:`.Environment`
     """
     def py27_comp(paths=None, safe=True):
         if paths is None:
@@ -237,7 +237,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:
@@ -271,7 +271,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: