[OpenLayers-Dev] Additional Documentation

Tim Schaub tschaub at opengeo.org
Thu Nov 13 14:44:01 EST 2008

Christopher Schmidt wrote:
> On Thu, Nov 13, 2008 at 11:19:34AM -0700, Tim Schaub wrote:
>> 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.
> Agreed that sphinx is good for the future. I think it proves its mettle
> in the content you've been working on with the workshop tutorial.
> However, for things like the spherical mercator text, I think it's a bit
> overkill, since this is really like one subsection of the docs -- until
> there is a more coherent pathway between them.
> Hopefully, we'll get to the point where sphinx is helpful -- until it
> is, just rst2html on its own is a lot better than nothing :)

Makes good sense.


> Regards,

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

More information about the Dev mailing list