[OpenLayers-Dev] Additional Documentation

[Christopher Schmidt]

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 :)

Regards,
-- 
Christopher Schmidt
MetaCarta