[IPython-dev] AttributeError when running sphinx docs

[Brian Granger]

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 ;-(

> Cheers,
>
> f
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev



-- 
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...
Name: sphinx-err-Dv_u_T.log
Type: application/octet-stream
Size: 6936 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20120810/29ced1fd/attachment.obj>