[IPython-dev] [IPython-User] How to build ipython documentation

[Fernando Perez]

Hi Wendell,

On Fri, Jul 23, 2010 at 1:21 PM, Wendell Smith <wackywendell at gmail.com> wrote:
>
>
> However, in order to get it to continue all the way through, I had to
> install twisted, foolscap, and wxpython - none of which are necessary for
> basic ipython. Is it supposed to be that way?

no, it shouldn't.  The problem is that sphinx, in order to build the
docs, needs to import the modules, as it does not parse its inputs.
So if you want to build a *complete* set of IPython docs where every
docstring is included, you'd need to have every dependency installed.
And since some are mutually incompatible (say cocoa and win32 stuff,
which by definition run on different platforms), it will never be
possible to have 100% coverage with this approach.

In practice we can make the docs build with only the stdlib by fixing
the scripts to avoid documenting certain subpackages when their
dependencies aren't met.  But packagers/distributors would still need
to have the full dependencies installed if they want to generate
complete docs, and this approach still strikes me as somewhat ugly.

I don't have a solid solution to this though, given how the need to
import modules is a constraint coming from sphinx.  Anyone with a good
idea on how to proceed here, I'm all ears...

Cheers,

f