[IPython-dev] AttributeError when running sphinx docs
ellisonbg at gmail.com
Fri Aug 10 23:12:04 EDT 2012
On Fri, Aug 10, 2012 at 7:09 PM, Fernando Perez <fperez.net at gmail.com> wrote:
> 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.
Yes, it completely fails. I am attaching the log of the TB that
finally kills it.
> 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.
Yep, silent errors like that are horrible. Can we set a flag to cause
warnings to halt the build?
> - 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.
We currently have this category, and it is logically sound. But these
days the notebook almost belongs at the top-level. But it does share
a lot with the other frontends. Maybe organize this "interactive"
section according to components: qtconsole, terminal, notebook,
kernel. But the kernel is more of a dev level thing.
> - 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.
I think we are ready to get rid of the plugin stuff. I will check on
that are submit a PR.
> - 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.
I almost think that the dev guide should be done as a github wiki -
basically use github for everything dev related. I think that will
encourage more people to keep those docs updated.
> This is a major project, though...
Yes, but for now I would be happy being able to build the docs, errors
and all ;-(
> IPython-dev mailing list
> IPython-dev at scipy.org
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu and ellisonbg at gmail.com
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 6936 bytes
Desc: not available
More information about the IPython-dev