Andrea Aime wrote: > 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? Actually it is pulling the file in over the web from the svn repo. It works by setting a default baseurl in the conf.py file, which looks like:
gsinclude_baseurl = "http://svn.codehaus.org/geoserver/trunk"; And the gsinclude directive uses that + all the info such as class name, package name and module to locate the file. And then pulls it in via http. If it can't find the file or is offline it simply issues a warning and continues on, and the code block is empty. We could change this so that is builds up the path into the source tree. The downside of which would be that you could not build the docs separately from the sources, the upside would be it would work offline.. > > 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? No additional installation required. I created a "sphinxext" directory which sits parallel do the "developer","user", and "docguide" directories. For each conf.py you need to point it at the extension directory, and enable the specific extension. So once someone who develops the extension commits it and updates any conf.py files, those updating won't have to do anything to enable it. > > Cheers > Andrea > -- 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 [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-devel
