Re: fun with sphinx

> Does this mean that everyone who wants to build the GeoServer docs have
> to also check out the full GeoServer source code as well?
>
> Thanks,
> Mike Pumphrey
> OpenGeo - http://opengeo.org
>
>
> Justin Deoliveira wrote:
>> 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
>>