[yt-dev] RFC: updating API docs

[Kacper Kowalik]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20170220/205aa5c7/attachment.pgp>