From 13254a30df4416a0e89734bcf85aff59d906df28 Mon Sep 17 00:00:00 2001
From: Dave Halter <davidhalter88@gmail.com>
Date: Sat, 14 Mar 2020 14:28:06 +0100
Subject: [PATCH] Docs: Restructure API overview

---
 docs/docs/api.rst   | 63 +++++++++++++++++++++++++++------------------
 jedi/__init__.py    |  1 +
 jedi/api/project.py | 10 ++++++-
 3 files changed, 48 insertions(+), 26 deletions(-)

diff --git a/docs/docs/api.rst b/docs/docs/api.rst
index 111fdf26..f1fafa0f 100644
--- a/docs/docs/api.rst
+++ b/docs/docs/api.rst
@@ -3,26 +3,10 @@
 API Overview
 ============
 
-.. currentmodule:: jedi
-
-Note: This documentation is for Plugin developers, who want to improve their
-editors/IDE autocompletion 
-
-If you want to use |jedi|, you first need to ``import jedi``.  You then have
-direct access to the :class:`.Script`. You can then call the functions
-documented here. These functions return :ref:`API classes
-<api-classes>`.
-
-
-Deprecations
-------------
-
-The deprecation process is as follows:
-
-1. A deprecation is announced in the next major/minor release.
-2. We wait either at least a year & at least two minor releases until we remove
-   the deprecated functionality.
+.. note:: This documentation is mostly for Plugin developers, who want to
+   improve their editors/IDE with Jedi.
 
+.. _api:
 
 API Documentation
 -----------------
@@ -35,20 +19,34 @@ The API consists of a few different parts:
 - :ref:`Python Versions/Virtualenv Support <environments>` with functions like
   :func:`.find_system_environments` and :func:`.find_virtualenvs`
 
-.. _api:
-
-Static Analysis Interface
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: jedi
+Script
+~~~~~~
 
 .. autoclass:: jedi.Script
     :members:
+
+Interpreter
+~~~~~~~~~~~
 .. autoclass:: jedi.Interpreter
     :members:
+
+Helper Functions
+~~~~~~~~~~~~~~~~
+
 .. autofunction:: jedi.preload_module
 .. autofunction:: jedi.set_debug_function
 
+.. _projects:
+
+Projects
+~~~~~~~~
+
+.. automodule:: jedi.api.project
+
+.. autofunction:: jedi.get_default_project
+.. autoclass:: jedi.Project
+    :members:
+
 .. _environments:
 
 Environments
@@ -65,6 +63,12 @@ Environments
 .. autoclass:: jedi.api.environment.Environment
     :members:
 
+Errors
+~~~~~~
+
+.. autoexception:: jedi.InternalError
+.. autoexception:: jedi.RefactoringError
+
 Examples
 --------
 
@@ -127,3 +131,12 @@ References:
     5
     >>> rns[0].column
     8
+
+Deprecations
+------------
+
+The deprecation process is as follows:
+
+1. A deprecation is announced in the next major/minor release.
+2. We wait either at least a year & at least two minor releases until we remove
+   the deprecated functionality.
diff --git a/jedi/__init__.py b/jedi/__init__.py
index d0140404..309ac3e8 100644
--- a/jedi/__init__.py
+++ b/jedi/__init__.py
@@ -43,6 +43,7 @@ from jedi.api.environment import find_virtualenvs, find_system_environments, \
     get_system_environment, InterpreterEnvironment
 from jedi.api.project import Project, get_default_project
 from jedi.api.exceptions import InternalError, RefactoringError
+
 # Finally load the internal plugins. This is only internal.
 from jedi.plugins import registry
 del registry
diff --git a/jedi/api/project.py b/jedi/api/project.py
index cbfb6bc8..f8fbd8f4 100644
--- a/jedi/api/project.py
+++ b/jedi/api/project.py
@@ -1,3 +1,6 @@
+"""
+Projects
+"""
 import os
 import errno
 import json
@@ -56,6 +59,9 @@ def _force_unicode_list(lst):
 
 
 class Project(object):
+    """
+    XXX
+    """
     _environment = None
 
     @staticmethod
@@ -199,7 +205,9 @@ class Project(object):
 
     def complete_search(self, string, **kwargs):
         """
-        
+        XXX
+
+        :yields: :class:`.Completion`
         """
         return self._search_func(string, complete=True, **kwargs)