[yt-dev] RFC: updating API docs

Nathan Goldbaum nathan12343 at gmail.com
Fri Mar 3 15:07:48 PST 2017


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 at 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 at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20170303/8dfac6f2/attachment.htm>


More information about the yt-dev mailing list