Justin Deoliveira ha scritto: > 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?
Well, first off, kudos to your python-fu :) It seems to be useful all right. You cited before that literalinclude requires the file to be on the local file system so is this building the file lookup (../../../src/main/src/main/java/... eek) in a much more manageable manner? To be extra sure: it does not require one to be online to build the docs right? (e.g., it does not access svn via http and the like, right?). > 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. The question that remains is, how is this extension integrating with our docs? Is it a file that's sitting along with the docs and just gets picked up during the build, or does it need to be installed in some special location? Cheers Andrea -- Andrea Aime 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
