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

[Jan-Wijbrand Kolman]

Hi,

Earlier on I announced the plan to move the documentation directory from 
the grok package to the groktoolkit package. Uli's feedback on this 
plan, made us rethink what exactly needs to be done.

This is my revised plan:

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

This is quite an undertaking, but I will try to dedicate some time to 
this to get this started.

Feedback is highly appreciated.

regards, jw