[IPython-dev] AttributeError when running sphinx docs
Sat Aug 11 10:55:15 CDT 2012
On 11 August 2012 03:21, Aaron Meurer <firstname.lastname@example.org> wrote:
> By the way, for SymPy, we've added docs building to our sympy-bot, as
> it's the only way that people even consider this in pull requests.
> Perhaps you might consider the same for your test_pr. Otherwise,
> people don't even know that things are not Sphinx friendly, and the
> build errors just accumulate.
We considered it, but we want to keep test_pr light and fast. There's
a weekly job on ShiningPanda to build the docs:
> One option would be to get rid of our auto-generated API docs. I'm
> reluctant to do this because that's the kind of thing that we never
> know who may regularly use them and we've had them for years. But I
> personally never use them, and they are the source of most of our
> build time as well as most of the errors and warnings. A bit brutal
> of a solution, but it would go a long way to making this more
> manageable. Thoughts?
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.
More information about the IPython-dev