[yt-dev] RFC: updating API docs

[Nathan Goldbaum]

It looks like Kacper figured out how to show the full API of subclasses, so
this is now a strict improvement over the status quo :)


On Fri, Mar 3, 2017 at 5:07 PM Nathan Goldbaum <nathan12343 at gmail.com>
wrote:

> 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/20170304/3bd37b89/attachment-0001.html>