« Return to Thread: fun with sphinx
Re: fun with sphinx
by Andrea Aime-4
::
Rate this Message:
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
Geoserver-devel@...
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
> 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
Geoserver-devel@...
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
« Return to Thread: fun with sphinx
| Free embeddable forum powered by Nabble | Forum Help |
