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