fun with sphinx

Hi folks,

So I spent some time writing developer docs for trunk today, and wrote
up developer notes about the web ui with a short tutorial. I would
provide the link but docs.geoserver.org seems to be down :(

Regardless, in doing so I found my self wanting a feature again with
sphinx that was a feature I always wanted out of confluence as well: The
ability to reference code directly out of svn instead of copying it
manually into a code block.

I have looked for the ability to do this in sphinx, and it seems this
sort of feature is only supported with python. Boo. The closest thing I
have found is the "literalinclude" directive:

http://sphinx.pocoo.org/markup/code.html?highlight=literalinclude#dir-literalinclude

Which is almost exactly what I want, however it requires files to be
local. It might work mucking with file paths referencing into the source
part of the tree via an external link... but that seemed hacky and
external links are painful.

So I decided to look into the sphinx extension system to see how hard it
would be to write a plugin that did this. And I met with some success. I
created an custom directive called "gsinclude" which basically looks
like this:

.. gsinclude:: CatalogInfo
    :module: main
    :package: org.geoserver.catalog

And the result looks like the following:

http://skitch.com/jdeolive/bs723/skunkworks-v1.0-documentation

And it works with all the line filtering goodness as well:

.. gsinclude:: CatalogInfo
    :module: main
    :package: org.geoserver.catalog
    :lines: 15-18

Leads to:

http://skitch.com/jdeolive/bs727/skunkworks-v1.0-documentation

Fun stuff. What I am wondering is what other people think about this
sort of custom extension? Useful at all?

It is also very possible that the sphinx gurus out there have a better
way to solve this, so I am all ears if they do. But a good exercise none
the less to become familiar with some the internal workings of sphinx.

-Justin

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

------------------------------------------------------------------------------
Enter the BlackBerry Developer Challenge  
This is your chance to win up to $100,000 in prizes! For a limited time,
vendors submitting new applications to BlackBerry App World(TM) will have
the opportunity to enter the BlackBerry Developer Challenge. See full prize  
details at: http://p.sf.net/sfu/Challenge
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@...
https://lists.sourceforge.net/lists/listinfo/geoserver-devel