Hi all,

If we one or two more people officially review this we should be able to merge it before docathon next week. That will make it faster to iterate on documentation PRs.

https://bitbucket.org/yt_analysis/yt/pull-requests/2526/prepopulate-api-docs-before-main-sphinx/diff

Nathan

On Mon, Feb 20, 2017 at 7:24 AM Kacper Kowalik <xarthisius.kk@gmail.com> wrote:

Hi all!
I'd like to bring PR 2526 to your attention. It introduces small, but
significant changes to the way how the API reference is built. Most
notably: it generates a one html page per *module* with classes and
methods as subsections, instead of a one page per method (as we do now).

An example deployment can be browsed here:
http://yt-project.org/docs/mock

There are couple of pros to this approach:

 * The build time is greatly reduced. It shaves a 0.5h from the total
build time on our server, also makes it feasible to build the API doc
locally (it takes 2m on my laptop vs over 1h before)
 * The lower number of pages creates a better searchindex. As an example
try searching for an 'AxisAlignedSlicePlot' phrase on 'docs/dev and' on
'docs/mock'.

A one con that Nathan identified is that methods of a parent class are
not explicitly listed for derived classes (it can be also observed on
the aforementioned AxisAlignedSlicePlot's page). Instead there's a link
to the parent class definition at the top of doc entry (Bases:
yt.visualization.plot_window.PWViewerMPL for AxisAlignedSlicePlot).
For someone heavily relying on a previous API doc structure, that's
going to be something to get used to.

I'd love to hear from y'all, either on the ml or directly on the pull
request.
Cheers,
Kacper

_______________________________________________
yt-dev mailing list
yt-dev@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org