RFC: updating API docs
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
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... Nathan On Mon, Feb 20, 2017 at 7:24 AM Kacper Kowalik <xarthisius.kk@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@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
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@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...
Nathan
On Mon, Feb 20, 2017 at 7:24 AM Kacper Kowalik <xarthisius.kk@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@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
participants (2)
-
Kacper Kowalik -
Nathan Goldbaum