[Geoserver-devel] Sphinx documentation for community modules

GeoServer GeoServer Developer
1

Hi all,

Andrea and I talked a bit today about having Sphinx documentation for community modules. Here's a transcript; hopefully we can finish up this discussion on the mailing list.

12:23 < aaime> jdeolive, community modules and documentation... confluence? I
guess I'd like it better to write direclty in sphinx, but we don't
have a place there
12:23 < aaime> (I guess we could make it)
12:24 < dwins> i've been meaning to bring this up too; i have a few pages on the
rhino extension that i wrote up in sphinx
12:24 < aaime> We have a tutorial section, we could have a "community" or
"preview" section
12:25 < aaime> it's important that we make it clear that the modules are not part
of the standard distribution though
12:25 < aaime> otherwise, confluence until the module gets supported, and then we
have to redo all the formatting (syntax change) to port over to
sphinx
12:25 < aaime> the downside of using sphinx is that the official release docs
would still contain the community modules stuff...
12:26 < aaime> is there a way to exclude bits and pieces from a sphinx build?
12:26 < dwins> i know you can have conditionals inside a document
12:26 < dwins> i don't know whether you can completely hide subtrees
12:29 < dwins> http://sphinx.pocoo.org/ext/ifconfig.html
12:29 < sigq> Title: sphinx.ext.ifconfig – Include content based on configuration
Sphinx v0.6.4 documentation (at sphinx.pocoo.org)
12:30 < aaime> sounds interesting
12:30 < aaime> generally speaking I guess would be nice to be able and do
something like
12:31 < aaime> make html -Prelease
12:31 < aaime> (mixing mvn and make syntax)
12:31 < aaime> so that the whole community subtree gets excluded
12:31 < aaime> well, I don't have to work on this right now, but we can copy this
chat and send it to the devel ml?
12:32 < aaime> dwins?
12:32 < dwins> sounds good to me
12:32 < aaime> cool, you do it? :-p
12:32 < dwins> okay, i will
12:32 < aaime> thanks!!!
12:32 < dwins> before you go though
12:32 < aaime> uh?
12:32 < dwins> i think it would be easier to keep them as separate sphinx projects
12:33 < dwins> and use intersphinx if we need to link to 'official' pages from
the community docs

--
David Winslow
OpenGeo - http://opengeo.org/

2

+1 to the different sphinx projects (helps avoid confusion).

Ariel Núñez // GeoSolutions S.A.S

3

My 2c on the subject:

jdeolive: aaime: re docs for community modules
[1:08pm] jdeolive: we could create another sphinx project, call it "pending" or "dev" or something
[1:08pm] jdeolive: and put all community docs there
[1:08pm] aaime: would work for me
[1:08pm] aaime: as long as it's published online
[1:08pm] aaime: so that we have online both the jars to try out and the docs
[1:09pm] aaime: would make for a good way to have peope test them out+
[1:09pm] jdeolive: cool, should be easy to publish to docs.geoserver.org/pending or something

We could create a new project or alternatively just create a new section in the existing user guide... but as stated in the below discussion it might take some trickery to ensure they are excluded from the main release docs.

I think just another section would be easier to manage, and I would be fine with them being shipped with the official release docs as long as their is a clear disclaimer at the top of each page stating that the docs are pending and do not document officially supported code.

-Justin

On 2/17/10 12:37 PM, David Winslow wrote:

Hi all,

Andrea and I talked a bit today about having Sphinx documentation for
community modules. Here's a transcript; hopefully we can finish up this
discussion on the mailing list.

12:23< aaime> jdeolive, community modules and documentation...
confluence? I
guess I'd like it better to write direclty in sphinx, but we don't
have a place there
12:23< aaime> (I guess we could make it)
12:24< dwins> i've been meaning to bring this up too; i have a few
pages on the
rhino extension that i wrote up in sphinx
12:24< aaime> We have a tutorial section, we could have a "community" or
"preview" section
12:25< aaime> it's important that we make it clear that the modules are
not part
of the standard distribution though
12:25< aaime> otherwise, confluence until the module gets supported,
and then we
have to redo all the formatting (syntax change) to port over to
sphinx
12:25< aaime> the downside of using sphinx is that the official release
docs
would still contain the community modules stuff...
12:26< aaime> is there a way to exclude bits and pieces from a sphinx
build?
12:26< dwins> i know you can have conditionals inside a document
12:26< dwins> i don't know whether you can completely hide subtrees
12:29< dwins> http://sphinx.pocoo.org/ext/ifconfig.html
12:29< sigq> Title: sphinx.ext.ifconfig – Include content based on
configuration
Sphinx v0.6.4 documentation (at sphinx.pocoo.org)
12:30< aaime> sounds interesting
12:30< aaime> generally speaking I guess would be nice to be able and do
something like
12:31< aaime> make html -Prelease
12:31< aaime> (mixing mvn and make syntax)
12:31< aaime> so that the whole community subtree gets excluded
12:31< aaime> well, I don't have to work on this right now, but we can
copy this
chat and send it to the devel ml?
12:32< aaime> dwins?
12:32< dwins> sounds good to me
12:32< aaime> cool, you do it? :-p
12:32< dwins> okay, i will
12:32< aaime> thanks!!!
12:32< dwins> before you go though
12:32< aaime> uh?
12:32< dwins> i think it would be easier to keep them as separate
sphinx projects
12:33< dwins> and use intersphinx if we need to link to 'official'
pages from
the community docs

--
David Winslow
OpenGeo - http://opengeo.org/

------------------------------------------------------------------------------
SOLARIS 10 is the OS for Data Centers - provides features such as DTrace,
Predictive Self Healing and Award Winning ZFS. Get Solaris 10 NOW
http://p.sf.net/sfu/solaris-dev2dev
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

4

Justin Deoliveira ha scritto:

I think just another section would be easier to manage, and I would be fine with them being shipped with the official release docs as long as their is a clear disclaimer at the top of each page stating that the docs are pending and do not document officially supported code.

I also prefer to just have a section in the main docs and keep
the build simple.
We do a significant introduction explaining that:
- the modules are not part of the release
- but they are part of the nightly builds
- they are community because they still haven't met the standards
   for extensions

And be done with it. Simple, easy. I like it.

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

5

I took the liberty of adding a section named "community" to the user guide.

http://docs.geoserver.org/trunk/en/user/community/index.html

I only added it on trunk. Do we think it necessary to create a community section on 2.0.x?

On 2/17/10 1:20 PM, Andrea Aime wrote:

Justin Deoliveira ha scritto:

I think just another section would be easier to manage, and I would be
fine with them being shipped with the official release docs as long as
their is a clear disclaimer at the top of each page stating that the
docs are pending and do not document officially supported code.

I also prefer to just have a section in the main docs and keep
the build simple.
We do a significant introduction explaining that:
- the modules are not part of the release
- but they are part of the nightly builds
- they are community because they still haven't met the standards
    for extensions

And be done with it. Simple, easy. I like it.

Cheers
Andrea

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

6

Justin Deoliveira ha scritto:

I took the liberty of adding a section named "community" to the user guide.

http://docs.geoserver.org/trunk/en/user/community/index.html

I only added it on trunk. Do we think it necessary to create a community section on 2.0.x?

I'd say.. yeah. Reasoning: the community modules distributed along with 2.0.x nightlies are more likely to be checked out by users.
And it would be a little odd to search for docs on trunk and then go
download on 2.0.x

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

7

On 2/18/10 2:02 PM, Andrea Aime wrote:

Justin Deoliveira ha scritto:

I took the liberty of adding a section named "community" to the user guide.

http://docs.geoserver.org/trunk/en/user/community/index.html

I only added it on trunk. Do we think it necessary to create a community
section on 2.0.x?

I'd say.. yeah. Reasoning: the community modules distributed along with
2.0.x nightlies are more likely to be checked out by users.
And it would be a little odd to search for docs on trunk and then go
download on 2.0.x

Makes sense. Done. Now a community section on 2.0.x as well.

Cheers
Andrea

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.