[IPython-dev] AttributeError when running sphinx docs
Fri Aug 10 21:09:55 CDT 2012
On Fri, Aug 10, 2012 at 5:40 PM, Brian Granger <email@example.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,
- 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...
More information about the IPython-dev