[OpenLayers-Dev] Additional Documentation

[Tim Schaub]

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.

Tim

> Regards,


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