[doc] Add atr's notes on inference and some TODOs

3 files changed, 105 insertions, 4 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index a0f177f..3483656 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -16,12 +16,12 @@ import sys, os
 # 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
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../../'))
 
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -54,7 +54,7 @@ release = '0.24.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -70,7 +70,7 @@ exclude_patterns = []
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
@@ -87,6 +87,11 @@ pygments_style = 'sphinx'
 #modindex_common_prefix = []
 
 
+# -- Customization --
+
+primary_domain = "py"
+todo_include_todos = True
+
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e28f37a..536a25d 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,6 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. Please see the documentation for the Sphinx Python domain :
+   http://sphinx-doc.org/domains.html#the-python-domain
+   and the autodoc extension
+   http://sphinx-doc.org/ext/autodoc.html
+
+
 Welcome to Astroid's documentation!
 ===================================
 
@@ -11,8 +17,11 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   inference
+
    extending
 
+
 Indices and tables
 ==================
 
diff --git a/doc/source/inference.rst b/doc/source/inference.rst
new file mode 100644
index 0000000..bf67993
--- /dev/null
+++ b/doc/source/inference.rst
@@ -0,0 +1,87 @@
+.. _inference:
+
+===================================
+  Inference on the AST in Astroid
+===================================
+
+Introduction
+============
+
+What/where is 'inference' ?
+---------------------------
+
+Well, not *inference* in general, but inference within *astroid* in
+particular... Basically this is extracting information about a node of
+the AST from the node's context so as to make its description
+richer. For example it can be most useful to know that this
+identifier node *toto* can have values among 1, 2.0, and "yesterday".
+
+The inference process entry-point is the :meth:`NodeNG.infer` method
+of the AST nodes which is defined in :class:`NodeNG` the base class
+for AST nodes. This method return a generator which yields the
+successive inference for the node when going through the possible
+execution branches.
+
+How does it work ?
+------------------
+
+.. todo :: double chek this :func:`infer` is monkey-patched point
+
+The :meth:`NodeNG.infer` method either delegates the actual inference
+to the instance specific method :meth:`NodeNG._explicit_inference`
+when not `None` or to the overloaded :meth:`_infer` method. The
+important point to note is that the :meth:`_infer` is *not* defined in
+the nodes classes but is instead *monkey-patched* in the
+:file:`inference.py` so that the inference implementation is not
+scattered to the multiple node classes.
+
+.. note:: The inference method are to be wrapped in decorators like
+          :func:`path_wrapper` which update the inference context.
+
+In both cases the :meth:`infer` returns a *generator* which iterates
+through the various *values* the node could take.
+
+.. todo:: introduce the :func:`inference.infer_end` method and
+   	  terminal nodes along with the recursive call
+
+In some case the value yielded will not be a node found in the AST of the node
+but an instance of a special inference class such as :class:`_Yes`,
+:class:`Instance`,etc. Those classes are defined in :file:`bases.py`.
+
+Namely, the special singleton :obj:`YES()` is yielded when the inference reaches
+a point where t can't follow the code and is so unable to guess a value ; and
+instances of the :class:`Instance` class are yielded when the current node is
+infered to be an instance of some known class.
+
+What does it rely upon ?
+------------------------
+
+In order to perform such an inference the :meth:`infer` methods rely
+on several more global objects, mainly :
+
+:obj:`MANAGER`
+    is a unique global instance of the class :class:`AstroidManager`,
+    it helps managing and reusing inference needed / done somewhere
+    else than the current invocation node.
+
+:class:`InferenceContext`
+    Instances of this class can be passed to the :meth:`infer` methods
+    to convey aditionnal information on the context of the current
+    node, and especially the current scope.
+
+.. todo:: Write something about :class:`Scope` objects and
+          :meth:`NodeNG.lookup` method.
+
+
+API documentation
+=================
+
+Here is the annotaded API documentation extracted from the source code
+of the :mod:`inference`.
+
+.. todo:: actually annotate the doc to structure its approach
+
+.. automodule:: inference
+   :members:
+   :undoc-members:
+.. :special-members: in autodoc/sphinx 1.1