What do you look for in a documentation tool?

written by Georg, on Monday, January 21, 2008 14:56.

In the last few days, I've tried to decouple Python's new documentation tool (called "Sphinx") from Python itself, so that other projects can use it too.

I know that the Python world is not short of documentation tools, but it would be a waste of effort not to make this small step and offer another hopefully useful tool to the community.

If you didn't pay attention to the new docs yet (see http://docs.python.org/dev for a daily build), these are some of the main features (implemented as needed for Python core docs):

Doc source is written in reStructuredText with some custom reST markup
Output formats are currently HTML, Windows HTML help, LaTeX
Easy definition of a document hierarchy
Automatic cross-linking of object names, terms and more information items
Index and module index building
Automated source highlighting

All in all it's a good choice if your documentation consists of reST files that you want to arrange into a consistent tree of docs.

What's different to many other documentation tools is that no generation of docs from docstrings is currently supported (Python never did this, all documentation is maintained separately). Of course, it's not impossible to add that capability, and Armin is looking into that already.

Therefore, I ask those of you who would be interested in using Sphinx for their projects: What features would you need/want/like? (Except for documentation, which is currently restricted to this document and will be extended soon.)

Comments

A tool that can easily (!) produce indexed HTML documentation in the standard 'Python format' would be greatly welcomed.

The ability to combine 'manually written' documentation with autogenerated API docs from docstrings would be a double boon.

IronPython compatibility would be a triple boon...

— Michael Foord on Monday, January 21, 2008 16:57 #
I had a long talk with Bruce Eckel and Mark Ramm at CodeMash about documentation tools recently.

One thing that is seriously needed is the ability to run and test code snippets in some fashion. It's just too easy for documentation to get out of date relative to the code, and if you can effectively "unit test" your docs, you're in much better shape.

And I don't mean like doctests, because not everything lends it self well to that style of testing. If it's possible to mark up some code as being for test fixture and some code as being what belongs in the doc, that would be good.

I'm also hoping for a multilingual tool (in the JavaScript, HTML, Python, etc. sense).

Note sure if Sphinx will ultimately be able to do all of that, but some tool will at some point, because some of us need such a thing :)

— Kevin Dangoor on Monday, January 21, 2008 18:29 #
For me a key is being able to test code in the docs, and think the key is being able to "annotate" a code snipit with information abut the context in which it should run, and the output it should give.

I'm willing to help out a bit, as are a few people I know if we can get a documentation tool we can use in our various projects. We're all kinda throwing together a few hacky things and have decided that we need to put some effort into making something robust enough that we can all share.

— Mark on Monday, January 21, 2008 19:29 #
Apydia (http://apydia.ematia.de/) is a project that is active at the moment. Catching doc projects in their brief periods of activity is all-important ;)

Since Apydia does extraction only maybe it'd be a good starting point.

I think reST and doctests have more potential than people immediately see. You can, for instance, put code in reST comments that doctest sees. Some Zope people have played with putting that setup code in footnotes, so it's not entirely gone but it's not too in-your-face. I'd really like if doctests had more contextual information themselves, or if doctest was just easier to extend. Then it might be easier to embed tests in the documentation (where the tests really run over the documentation, they aren't documentation themselves). Or, with other kinds of parsers for doctests, stuff like HTML output could be more usefully embedded in the document.

— Ian Bicking on Monday, January 21, 2008 21:43 #
A small thing; I have libraries that fit into larger systems. Pylons is a classic example, with lots of libraries that provide core things. The ability to cross link between all those projects would be great.

Links into source code is also nice. The standard library would benefit from this too.

— Ian Bicking on Monday, January 21, 2008 21:44 #
Largely inspired by your work on the Python documentation, I have started writing reST files as unit tests, one for each module of my pet project (Crunchy). It is working quite nicely and will be included in the next release.

However, as Kevin and Mark have alluded to, I could see the need to embed (in a hidden way) the setup and expected output of a given test for straight documentation.

Currently I am running the tests using a simple module that imports them all.

An alternative to the traditional testing, that I have used for fun, was to load up a given reST page using Crunchy and have the tests executed in "chunks" (tests are interspersed with textual information), literally at the click of two buttons for each "chunk". I have toyed with the idea of implementing a small Crunchy plugin that would allow to run all the tests on a page, just by clicking on a single button - but this would have been less simple than simply typing
"python all_tests.py".

However, for the idea mentioned by Kevin and Mark, I think the other Crunchy-based approach could work - and would not be too complicated to implement.

— André on Monday, January 21, 2008 23:29 #
I'd like a format that can be diffed and still be presentable in the same format. This would probably require the format's tool set to include a diff tool.

— john saponara on Tuesday, January 22, 2008 18:07 #
Thanks for all your valuable comments! I'll try to keep them in mind while extending Sphinx.

Mark, I really appreciate your offer -- do you want to write me an email (georg at python org) to coordinate?

— Georg on Sunday, January 27, 2008 18:05 #
Where can I try out "Sphinx"?

Thanks,
Swaroop

— Swaroop C H on Monday, February 18, 2008 11:01 #
It's currently only available from Subversion (http://svn.python.org/projects/doctools/sphinx).

I'll be making cheeseshop packages soon.

— Georg on Wednesday, February 20, 2008 7:47 #
Does anyone know how (if possible) to tell Sphinx to include the source of each function/method next to the documentation for that function/method? I imagine it would be collapsed in an expandable div for example, and would appear syntax highlighted when expanded.

I've really gotten to like this feature in the Rails documentation (eg here's an illustration: http://api.rubyonrails.org/classes/ActionController/Caching/Fragments.html)

Often, manual documentation doesn't completely capture the behaviour of a bit of code, so reading the source can be crucial.

— Brian on Tuesday, July 22, 2008 20:09 #
@Brian: there is currently no such functionality in Sphinx; however, I've on my todo list an extension that highlights the source code, puts it next to the translated HTML, and adds links between them.

This extension could probably also support putting the code inline.

— Georg on Tuesday, July 29, 2008 18:34 #

Commenting is no longer possible.