<div>Hi all,</div><div><br></div><div>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.</div><div><br></div><div><a href="https://bitbucket.org/yt_analysis/yt/pull-requests/2526/prepopulate-api-docs-before-main-sphinx/diff">https://bitbucket.org/yt_analysis/yt/pull-requests/2526/prepopulate-api-docs-before-main-sphinx/diff</a><br></div><div><br></div><div>Nathan</div><div><br><div class="gmail_quote"><div>On Mon, Feb 20, 2017 at 7:24 AM Kacper Kowalik <<a href="mailto:xarthisius.kk@gmail.com">xarthisius.kk@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi all!<br class="gmail_msg">
I'd like to bring PR 2526 to your attention. It introduces small, but<br class="gmail_msg">
significant changes to the way how the API reference is built. Most<br class="gmail_msg">
notably: it generates a one html page per *module* with classes and<br class="gmail_msg">
methods as subsections, instead of a one page per method (as we do now).<br class="gmail_msg">
<br class="gmail_msg">
An example deployment can be browsed here:<br class="gmail_msg">
<a href="http://yt-project.org/docs/mock" rel="noreferrer" class="gmail_msg" target="_blank">http://yt-project.org/docs/mock</a><br class="gmail_msg">
<br class="gmail_msg">
There are couple of pros to this approach:<br class="gmail_msg">
<br class="gmail_msg">
 * The build time is greatly reduced. It shaves a 0.5h from the total<br class="gmail_msg">
build time on our server, also makes it feasible to build the API doc<br class="gmail_msg">
locally (it takes 2m on my laptop vs over 1h before)<br class="gmail_msg">
 * The lower number of pages creates a better searchindex. As an example<br class="gmail_msg">
try searching for an 'AxisAlignedSlicePlot' phrase on 'docs/dev and' on<br class="gmail_msg">
'docs/mock'.<br class="gmail_msg">
<br class="gmail_msg">
A one con that Nathan identified is that methods of a parent class are<br class="gmail_msg">
not explicitly listed for derived classes (it can be also observed on<br class="gmail_msg">
the aforementioned AxisAlignedSlicePlot's page). Instead there's a link<br class="gmail_msg">
to the parent class definition at the top of doc entry (Bases:<br class="gmail_msg">
yt.visualization.plot_window.PWViewerMPL for AxisAlignedSlicePlot).<br class="gmail_msg">
For someone heavily relying on a previous API doc structure, that's<br class="gmail_msg">
going to be something to get used to.<br class="gmail_msg">
<br class="gmail_msg">
I'd love to hear from y'all, either on the ml or directly on the pull<br class="gmail_msg">
request.<br class="gmail_msg">
Cheers,<br class="gmail_msg">
Kacper<br class="gmail_msg">
<br class="gmail_msg">
_______________________________________________<br class="gmail_msg">
yt-dev mailing list<br class="gmail_msg">
<a href="mailto:yt-dev@lists.spacepope.org" class="gmail_msg" target="_blank">yt-dev@lists.spacepope.org</a><br class="gmail_msg">
<a href="http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org" rel="noreferrer" class="gmail_msg" target="_blank">http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org</a><br class="gmail_msg">
</blockquote></div></div>