[IPython-dev] AttributeError when running sphinx docs

[Fernando Perez]

On Sat, Aug 11, 2012 at 8:55 AM, Thomas Kluyver <takowl at gmail.com> wrote:
> On other projects I've worked on, I've found it quite good discipline
> to have to write API docs 'manually': specifying the names of classes
> and functions for Sphinx autodoc. It forces you to think about what
> parts you want third parties to be relying on, rather than
> mechanically listing every helper method you've defined. Then again,
> those projects have been much smaller than IPython.

I'm not opposed to that at all: having an auto-generated dump was the
'quick way out' when we were just getting our feet wet with sphinx,
and we adapted a pymvpa script for our needs.  But given the problems
it gives us, and the (valid) point your raise above, it might not be a
bad idea to cut our losses by nuking the auto-generated docs
altogether, and start gradually building API docs manually by
including only what makes sense to declare publicly.

I'm starting to think towards a 1.0 horizon, and it would certainly
*much* better to have 1.0 land with a clean API documentation, since
to a good extent just about the only thing that will distinguish 1.0
from other 0.x releases will be our statement of commitment to its
API.  IPython has been 'production ready' for years, but we're finally
getting to the point where we feel the internal design, structure and
capabilities are where we want them, and we can mark that with an
official 1.0 release.

But it will be very awkward to do so if our docs are a dump of every
last dark corner in our codebase.  And since asking that we clean
every single function and method in ipython before 1.0 is unrealistic
(we'd never clear that bar), it may be wiser to instead say that the
public API is only whatever we've built docs for, and that the rest
should be considered private, even if it has decent dosctrings.

If we all agree with this view of things, then we should *sooner*
rather than later nuke the automatic API docs, and start slowly adding
things back up manually.  The initial PR that does this could be very
simple and only create the minimal template adding a module or two, we
can always build that up slowly.

As I type this, I'm growing increasingly convinced that it's a good
idea... Thoughts, dissent?

Cheers,

f