[OpenLayers-Dev] Additional Documentation
crschmidt at metacarta.com
Thu Nov 13 13:27:15 EST 2008
On Thu, Nov 13, 2008 at 11:19:34AM -0700, Tim Schaub wrote:
> 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 :)
More information about the Dev