That looks really great, congrats. It is indeed a long awaited feature wrt docs.
It would be _perfect_ imho, if instead of having to reference code snipets through line numbers it could be done through some sort of tagging (so the file can evolve without breaking the docs). But I've no idea whether that's possible or how :( excellent work Gabriel 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 > -- Gabriel Roldan OpenGeo - http://opengeo.org Expert service straight from the developers. ------------------------------------------------------------------------------ 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 [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-devel
