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.
On Mon, Feb 20, 2017 at 7:24 AM Kacper Kowalik email@example.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 firstname.lastname@example.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org