Improves documentation (closes #1)

.gitignore

@@ -9,3 +9,4 @@ parts
 *.egg-info
 src
 develop-eggs
+sphinx/

doc/conf.py

@@ -25,14 +25,35 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
+    #'matplotlib.sphinxext.plot_directive'
     ]
 
 import sphinx
 if sphinx.__version__ >= "1.4.1":
     extensions.append('sphinx.ext.imgmath')
+    imgmath_image_format = 'svg'
 else:
     extensions.append('sphinx.ext.pngmath')
 
+# Be picky about warnings
+nitpicky = True
+
+# Ignores stuff we can't easily resolve on other project's sphinx manuals
+nitpick_ignore = []
+
+# Allows the user to override warnings from a separate file
+if os.path.exists('nitpick-exceptions.txt'):
+    for line in open('nitpick-exceptions.txt'):
+        if line.strip() == "" or line.startswith("#"):
+            continue
+        dtype, target = line.split(None, 1)
+        target = target.strip()
+        try: # python 2.x
+            target = unicode(target)
+        except NameError:
+            pass
+        nitpick_ignore.append((dtype, target))
+
 # Always includes todos
 todo_include_todos = True
 
@@ -216,8 +237,16 @@ autodoc_default_flags = [
   ]
 
 # For inter-documentation mapping:
-from bob.extension.utils import link_documentation
-intersphinx_mapping = link_documentation()
+from bob.extension.utils import link_documentation, load_requirements
+sphinx_requirements = "extra-intersphinx.txt"
+if os.path.exists(sphinx_requirements):
+  intersphinx_mapping = link_documentation(
+      additional_packages=['python','numpy'] + \
+          load_requirements(sphinx_requirements)
+          )
+else:
+  intersphinx_mapping = link_documentation()
+
 
 # We want to remove all private (i.e. _. or __.__) members
 # that are not in the list of accepted functions

doc/index.rst

 .. vim: set fileencoding=utf-8 :
-.. @author: Teodors Eglitis <Teodors.Eglitis@idiap.ch>
-.. @date:   Wed Aug 17 14:47:18 CEST 2016
 
 .. _bob.ip.annotator:
 
@@ -20,6 +18,7 @@ Documentation
    annotator-guide
    line-annotator-guide
    point-annotator-guide
+   py_api
 
 
 Indices and tables
@@ -30,5 +29,3 @@ Indices and tables
 * :ref:`search`
 
 
-.. automodule:: bob.ip.annotator
-

doc/py_api.rst

+.. vim: set fileencoding=utf-8 :
+
+============
+ Module API
+============
+
+.. automodule:: bob.ip.annotator