[IPython-dev] AttributeError when running sphinx docs

[Fernando Perez]

On Fri, Aug 10, 2012 at 5:40 PM, Brian Granger <ellisonbg at gmail.com> wrote:
> When I run "make html" to build the sphinx docs, I see a long sequence
> of AttributeErrors - all on IPython attributes that clearly exist.
> All of these are happening in the autodoc sphinx extension.  I have a
> vague recollection of seeing this before but have no idea what I did
> to get it to run.  Has anyone seen this or know what is going on?

Do they stop the build for you?  Because I do see all of those, but
they go by and eventually the build does complete.

Now, we are in *major* need of a massive doc cleanup project, that should:

- begin by fixing all those errors and warnings of the build process
so that in the future, we can actually pay attention to new
warnings/errors.  Now there's so much noise in the build that, unless
it flat out fails, we simply ignore all the noise.

- then, start organizing the docs in a more friendly and useful way
that they are today.

I think basically our docs should have an intro layout similar to that
of StarCluster's fantastic documentation
(http://web.mit.edu/star/cluster), and there should at least be the
following main areas:

- Introductory overview, meant to take ~15 minutes of reading and to
give people a useful understanding of the available tools without
overwhelming them with detail.  Lots of screenshots and examples,
little prose.

- IPython for interactive use.  We have a lot of this material, but
it's a mix of high and low-level detail that makes it hard to read.

- IPython for parallel computing.

- Using IPython as a library for your own applications: the "IPython SDK".

- Configuring, customizing and extending IPython: we need to
rationalize the zoo of plugins/extensions/hooks concepts we use into
just a few, and describe each with some clear examples.  At this point
I don't even remember all we have.

- The architecture of IPython: I think that we should have a dedicated
section that's a reference with a few diagrams that explain the
various moving parts in a high-level way.  Key objects, protocols and
ways in which they are organized.  The SDK can refer to this and
expand it in more detail, but I think that having a single high-level
view of the whole project we can refer to would be very useful.

- Developer's guide for hacking *on* IPython itself.  This should be
fairly short and we mostly have it.


This is a major project, though...

Cheers,

f