Hey all. We've talked before about maintaining an admin/developer manual for GeoNode in Sphinx, and my sphinx-docs branch that provides a skeleton for such a manual. I think it's about time to bring that branch onto master and start populating it in anticipation of the 1.0 release (we've already gotten a few bug reports about the lack of documentation). I think we are in unanimous agreement that Sphinx is a good idea. However, there are a few details to sort out: Where to host the manual? * We already have http://dev.geonode.org/ ; this seems like a great place. What theme to use? * The old docs used a lightly modified copy of the GeoExt Sphinx theme. I don't think there are any restrictions on the use of this theme, so we could continue to do so. But my feeling is that if we are not going to use a GeoNode theme (that mimics the demo site and the blog) then we may as well stick with the Sphinx defaults. I don't feel strongly one way or the other about this though. -- David Winslow OpenGeo - http://opengeo.org/
> > Where to host the manual? > * We already have http://dev.geonode.org/ ; this seems like a great place. > I think this makes sense for developer-facing docs especially. For user-facing docs it's a bit misleading-- I think docs.geonode.org would be better. But if it's a hassle to separate the two at this point dev works as an interim thing. In the future, we may want to consider hosting our project Trac (or whatever we end up using) at dev.geonode.org. What theme to use? > * The old docs used a lightly modified copy of the GeoExt Sphinx theme. I > don't think there are any restrictions on the use of this theme, so we could > continue to do so. But my feeling is that if we are not going to use a > GeoNode theme (that mimics the demo site and the blog) then we may as well > stick with the Sphinx defaults. > +1 -- Sebastian Benthall OpenGeo - http://opengeo.org
Check out the URL structure at http://docs.geoserver.org/ for a template we might want to follow. On Fri, Aug 13, 2010 at 11:22 AM, Sebastian Benthall <seb@opengeo.org>wrote: > Where to host the manual? >> * We already have http://dev.geonode.org/ ; this seems like a great >> place. >> > > I think this makes sense for developer-facing docs especially. > > For user-facing docs it's a bit misleading-- I think docs.geonode.orgwould be better. But if it's a hassle to separate the two at this point dev > works as an interim thing. > > In the future, we may want to consider hosting our project Trac (or > whatever we end up using) at dev.geonode.org. > > What theme to use? >> * The old docs used a lightly modified copy of the GeoExt Sphinx theme. I >> don't think there are any restrictions on the use of this theme, so we could >> continue to do so. But my feeling is that if we are not going to use a >> GeoNode theme (that mimics the demo site and the blog) then we may as well >> stick with the Sphinx defaults. >> > > +1 > > -- > Sebastian Benthall > OpenGeo - http://opengeo.org > >
On 8/11/10 12:38 PM, David Winslow wrote: > Where to host the manual? > * We already have http://dev.geonode.org/ ; this seems like a great place. indeed > > What theme to use? > * The old docs used a lightly modified copy of the GeoExt Sphinx theme. I > don't think there are any restrictions on the use of this theme, so we could > continue to do so. But my feeling is that if we are not going to use a > GeoNode theme (that mimics the demo site and the blog) then we may as well > stick with the Sphinx defaults. I don't feel strongly one way or the other > about this though. agreed on default till having an actual geonode theme. Which leads to the question, how much of a hurdle would it be to ask Rollie to adapt the geonode theme at geonode.org for sphinx? Gabriel > > -- > David Winslow > OpenGeo - http://opengeo.org/ >
On Wed, Aug 11, 2010 at 10:47 AM, Gabriel Roldan <groldan@opengeo.org> wrote: > On 8/11/10 12:38 PM, David Winslow wrote: > >> Where to host the manual? >> * We already have http://dev.geonode.org/ ; this seems like a great place. > indeed What about docs.geonode.org ? Ariel.
Okay, I'm merging sphinx-docs into the master branch. If you want to build
locally, you can install Sphinx ("pip install sphinx" works great) and use
the makefile in docs. Or, you can install sphinx and then use "paver html"
if you want to avoid installing make or something. The built docs end up in
docs/_build/html/ either way.
Some TODOs:
* Extract API docs from JavaScript and Java source trees and include them
somehow.
* Improve installation guide (double check that everything I wrote a couple
of months ago is still valid, explain all the gotchas with GeoNetwork
settings and GeoServer environment variables and Apache parameters).
* OS-Specific setup guides
* Include updating the docs in crucible day activities.
* Sphinx tweaks? I know the Django project uses a Sphinx extension that
helps with documenting fields that go in settings.py and views and such,
maybe we should crib that.
I'm not ticketing these because they are pretty vague. Feel free to
document things as they seem to need it (I'm happy to play editor if anyone
wants a "code review" on new stuff for the docs). I think everyone is
already familiar with Sphinx and RST syntax, but if you need a reference,
the Sphinx docs themselves are pretty good:
http://sphinx.pocoo.org/contents.html
--
David Winslow
OpenGeo - http://opengeo.org/
On Wed, Aug 11, 2010 at 12:02 PM, Ariel Nunez <ingenieroariel@gmail.com>wrote:
> On Wed, Aug 11, 2010 at 10:47 AM, Gabriel Roldan <groldan@opengeo.org>
> wrote:
> > On 8/11/10 12:38 PM, David Winslow wrote:
> >
> >> Where to host the manual?
> >> * We already have http://dev.geonode.org/ ; this seems like a great
> place.
> > indeed
>
> What about docs.geonode.org ?
>
> Ariel.
>