Improve documentation on Sphinx configuration, closes #17

templates/README.md

@@ -87,8 +87,8 @@ Two possible cases:
    [this file](http://www.gnu.org/licenses/gpl.txt) on the root of your package
    with the name `COPYING` instead
 
-**Important note**: change the name and email in setup.py to the maintainer of 
-the package (you in most cases). Andre Anjos is used as an example, do not put 
+**Important note**: change the name and email in setup.py to the maintainer of
+the package (you in most cases). Andre Anjos is used as an example, do not put
 his name everywhere.
 
 Download commands:
@@ -220,6 +220,25 @@ $ sed -i "s/<PROJECT>/`basename $(pwd)`/g" doc/conf.py
 $ sed -i "s%<SHORT_DESCRIPTION>%Building of Python/C++ extensions for Bob%g" doc/conf.py
 ```
 
+The new documentation configuration allows for two *optional* configuration
+text files to be placed along `conf.py` (on the same directory):
+
+* `extra-intersphinx.txt`, which lists extra packages that should be
+  cross-linked to the documentation (as with [Sphinx's intersphinx
+  extension](http://www.sphinx-doc.org/en/stable/ext/intersphinx.html). The
+  format of this text file is simple: it contains the PyPI names of packages to
+  cross-reference. One per line.
+* `nitpick-exceptions.txt`, which lists which documentation objects to ignore
+  (for warnings and errors). The format of this text file is two-column. On the
+  first column, you should refer to [Sphinx the object
+  type](http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain),
+  e.g. `py:class`, followed by a space and then the name of the that should be
+  ignored. E.g.: `bob.bio.base.Database`. The file may optionally contain empty
+  lines. Lines starting with `#` are ignored (so you can comment on why you're
+  ignoring these objects). Ignoring errors should be used only as a **last
+  resource**. You should first try to fix the errors as best as you can, so
+  your documentation links are properly working.
+
 ## 7. Update the logo on your project
 
 Please update the logo of your project (on the Settings), just set it to [this one](templates/bob-128x128.png).