[OpenLayers-Dev] Additional Documentation

[Tim Schaub]

Hey-

Christopher Schmidt wrote:
> 
> Does anyone have any objections to creating trunk/doc/, putting some
> useful build utils in it, as well as creating subdirectories for
> individual prose documentation efforts, starting with the
> spherical_mercator.rst describe above? 
> 

No objections.  +1 for sure.

My only suggestion would be to consider Sphinx (and this can be 
implemented later).  It adds a bit more structure to the HTML output - 
and works well for (ordered) prose docs.

My biggest wiki-peeve (don't think this was on your list) is that a wiki 
is completely unstructured.  Obviously there are conventions to impose 
structure - but I think they tend toward chaos.  Sphinx works best with 
a hierarchy and uses tables of contents in docs to determine 
relationships between docs - and ultimately the order in which they 
would be read were they part of a book.

Plus, the ".. code-block:: javascript" highlighting is nice (with 
pygments).  And the PDF output (via LaTeX) is actually pretty.

Anyway, maybe the build stuff you have in mind is similar (or same).

Tim

> I'll start off by saying I'm +1.
> 
> Regards,


-- 
Tim Schaub
OpenGeo - http://opengeo.org
Expert service straight from the developers.