[IPython-dev] problems building documentation with sphinx-0.6.1

[Fernando Perez]

Hi Darren,

2009/4/1 Darren Dale <dsdale24 at gmail.com>:
> I upgraded to sphinx-0.6.1 this morning and ran into some trouble. I've been
> trying to track down the cause, attempting to build the docs for my own
> projects (segfaults), numpy (issues, expecting segfaults), h5py (segfaults),
> and now ipython (issues). As of version 0.6, a tag can be provided to
> sphinx-build (perhaps in a make file or python equivalent) and then we can
> do, for example:
>
> .. only:: html
>
> But until IPython is ready to require >sphinx-0.6, perhaps someone could
> patch only_directives.py so it is compatible with version 0.6 and later:

Thanks a lot, I applied your patch so we can continue to build with
old as well as newer versions.

I pushed it to trunk right away, since it's so tiny and just for doc
building (I did test it and indeed it fixes the problem with current
sphinx).

> Has anyone tried building the ipython docs lately? After applying that
> patch, I try to build ipython's docs and I get an error when sphinx gets to
> IPython/frontend/frontendbase:
>
> -------
> /usr/local/src/ipython/docs/sphinxext/docscrape.py:117: UserWarning: Unknown
> section Result
>   warn("Unknown section %s" % key)
> /usr/local/src/ipython/docs/sphinxext/docscrape.py:117: UserWarning: Unknown
> section Parameters:
>   warn("Unknown section %s" % key)
> -------
>
> Followed by another error, which is probably not a concern since I don't
> have wxpython, but I thought I would report it anyway:
>
> -------
> Exception occurred:[ 22%] api/generated/IPython.frontend.wx.console_widget
>   File "/usr/local/src/ipython/docs/sphinxext/inheritance_diagram.py", line
> 107, in _import_class_or_module
>     "Could not import class or module '%s' specified for inheritance
> diagram" % name)
> ValueError: Could not import class or module
> 'IPython.frontend.wx.console_widget' specified for inheritance diagram
> The full traceback has been saved in /tmp/sphinx-err-axFWA0.log, if you want
> to report the issue to the author.
> Please also report this if it was a user error, so that a better error
> message can be provided next time.
> Send reports to sphinx-dev at googlegroups.com. Thanks!
> make: *** [html] Error 1
> ------

I see these too, thanks for reporting them.  We need to make sure our
test suite runs without dependencies, and we have test decorators for
that.  But I don't know how to put in conditional directives for doc
builds.  Any ideas?

Cheers,

f