Misc. problems in our Sphinx based docs

[ipython]

Original Launchpad bug 413776: https://bugs.launchpad.net/ipython/+bug/413776
Reported by: ellisonbg (Brian Granger).

I am observing multple problems with the Sphinx based documentation. I am using the 0.11 trunk and Sphinx 0.6.2. We need to go through our docs and probably do the following:

• Update all of our extensions to the latest version from matplotlib, etc.
• Fix all the errors we are having with our api docs.

Here are some of the actual errors:
1.

WARNING: extension 'ipython_console_highlighting' has no setup() function; is it really a Sphinx extension module?

/Users/bgranger/Documents/Computation/IPython/Code/inputhook/docs/sphinxext/docscrape.py:117: UserWarning: Unknown section Options
warn("Unknown section %s" % key)

1. When reading sources, Sphinx gives MANY (WARNING/2) errors about problems with our module docstrings.
2. Then we get lots of these:

(WARNING/2) toctree references unknown document u'api/generated/generated/IPython.config.api'

checking consistency... /Users/bgranger/Documents/Computation/IPython/Code/inputhook/docs/source/api/generated/gen.txt:: WARNING: document isn't included in any toctree
done

[fperez]

At the original Launchpad bug report, Barry Warsaw wrote:

Note. Problem #1 is blocking several package builds in Ubuntu 11.04, natty: https://bugs.launchpad.net/ubuntu/+source/nipy/+bug/685180

[minrk]

Some further notes on this:

• Modules that raise an ImportError should be ignored, not crash sphinx (unavailability of gtk, wx, etc.)
• shouldn't crash sphinx if no classes in a module for InheritanceDiagram (see IPython.util.wildcard)
• try to use IPython from the same directory for API docs, rather than always using installed IPython (or at least check and warn)

[minrk]

There have been lots of improvements here, no reason to keep this open.