[Grok-dev] the plan for moving documentation from the grok package to groktoolkit

[Jan-Wijbrand Kolman]

Hi,

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
> documentation.

On the branch:

   http://svn.zope.org/groktoolkit/branches/jw-documentation-rearangement/

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:

 
http://svn.zope.org/grok/branches/jw-documentation-rearangement/doc/api.rst?view=markup

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 :-)

Next steps:

* 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...

regards, jw