[Grok-dev] the plan for moving documentation from the grok package to groktoolkit
janwijbrand at gmail.com
Thu Jan 13 07:30:42 EST 2011
On 1/12/11 16:11 PM, Jan-Wijbrand Kolman wrote:
> * API documentation, tied to a specific package, will stay with the
> respective package.
> To extract API documentation and render it, each of the packages we care
> about (grok, grokcore.*, perhaps martian, etc.) requires sphinx
> infrastructure (similar to, for example, the fanstatic package, but of
> course there are many more packages out there with reasonable extracted
> API documentation we can use for inspiration).
> * Higher-level documentation like upgrade notes, tutorials, how-tos,
> "What's new", developer notes, etc. - in other words documentation that
> is about the Grok Project and what you can do with it - will go into the
> Grok Toolkit.
> This documentation tree requires sphinx infrastructure resembling that
> what currently is in the doc directory of grok. It also requires ways
> for integrating (parts of) the API documentations into this higher-level
On the branch:
I started moving documentation around. Most of the docs that used to be
in the grok now is in groktoolkit. The grok package now generates "API"
documentation, using Sphinx' autodoc features. See:
I was tempted to use the ``..automodule:: grok`` directive, which would
extract documentation for everything in the __init__.py of the grok
package, but I decided to "manually" include the contents in order to
group components, control the order and to exclude certain things.
When you generate the documentation for the grok package (on this
branch) you will conclude that there's quite some work still to be done
if it comes to documenting the grok APIs. But at least that work will be
worth it, as the doc strings will then be rendered and published nicely :-)
* Unless there's reason not too, I'd like to merge these documentation
rearrangement branches soon. At least before the next grok release. I
think this is safe, as we will not make the documentation worse.
* Find out how to elegantly integrate the documentation for a specific
package (say the grok package) into the documentation tree of the
groktoolkit. The intersphinx extension might help there.
* Organize an major editorial effort to improve and update the
documentation in the groktoolkit.
* Write documentation for the grokcore.* packages, martian, and what not...
More information about the Grok-dev