[Grok-dev] grok documentation, again

[Jan-Jaap Driessen]

On 9 February 2011 09:35, Jan-Wijbrand Kolman <janwijbrand at gmail.com> wrote:
> hi,
>
> Last weeks I have been on and off working on rearranging Grok's
> documentation. It has moved from the grok package to the groktoolkit. I
> tried to simplify the documentation-generation and for the recent
> releases *and* for the development version, the documentation on the
> grok.zope.org website is generated from this:
>
>   http://grok.zope.org/doc/current/
>   http://grok.zope.org/doc/1.3.2/
>   http://grok.zope.org/doc/dev/  <-- build every hour from the trunk
>
> The community documentation is build every hour on this URL:
>
>   http://grok.zope.org/doc/community/
>
> For the groktoolkit trunk I started rearranging the documentation
> structure. Most importantly, the packages document..:
>
>   http://grok.zope.org/doc/dev/packages.html
>
> ..is automatically generated during the documentation build process.
> Furthermore I added a releases document here:
>
>   http://grok.zope.org/doc/dev/releases.html
>
> It is my intention to replace the current "releases" page in Plone with
> this one as it is much easier to update this document when making a release.
>
> Originally we had a link to a the change log too in this documentation
> tree. Since the groktoolkit has no change log *and* the change log of
> just the grok package is by for not enough, I removed it. I'd like to
> generate a change log page for all of the groktoolkit packages somehow
> as it is important information.
>
> While working on all of this, I realized this:
>
> We have *a lot* of documentation lying around. We really do!
>
> But its organization is far from optimal by now *and* most of the
> documents need a round of updates. In other words, if we - as grok
> community - do care for good documentation, we need to again put some
> effort in it.
>
> Some of the todo items I see now:
>
> * Start adding descriptive docstrings to all the components in the
> grokcore.* family and related packages. If we do that the "sphinx-way"
> we can generate package documentation very neatly.
>
> * There are some packages (like grokcore.component) that have a fairly
> elaborate README.txt. While this is good(!), we need to somehow
> consolidate this worthwhile information into one easily found place.
>
> * Update the tutorial. The tutorial needs to be tested against recent
> Grok release.
>
> * Update the reference. The reference document contains lots of useful
> information. Some of this information might actually belong in the
> individual packages perhaps. Sphinx has tools to aggregate this
> information into one nice document.
>
> * Finish the transition from Plone to the sphinx based community
> documentation.
>
> * Consider what documents from the community docs might be better places
> in the "official" tree.
>
>
> All of this will take A Fair Amount of Organization and Hard Work.
>
> If you find yourself with an hour to spare and want to help out with
> this, please coordinate on IRC and/or on the list with us. You can ask
> me for questions regarding building the documentation tree, and perhaps
> about the organization of the documents. You can also talk to me about
> how to integrate the various documentation trees into one.
>
> regards, jw

Hi JW,

Thank you for doing all this tedious and unthankful work. I'll try to
help where necessary.

-- 
Jan-Jaap Driessen