[Pulp-list] What do you want from an API documentation solution?

[Nick Coghlan]

On 11/15/2011 05:42 AM, Jay Dobies wrote:
> * The biggest benefit to sphinx is co-locating the docs in the
> codebase which arguably isn't necessarily a benefit; you can put a
> browser editing a wiki side-by-side with code and not have to scroll
> up and down to hop between impl and docstring.

The big benefit of in-tree documentation is that you get full source
control over your docs. When you branch the code, you branch your docs
as well, so it is *much* easier to update them as you go without
affecting anyone else. Patches can come with included doc updates (and
you can even cite "no docs" as a reason for postponing acceptance of a
patch). When you tag the tree, you tag the docs, so releases and their
documentation are in lockstep. Also, because the docs are in your local 
checkout rather than locked away inside a web service, you can update 
them while offline.

Overall, it makes it very simple to manage your code, tests and docs as
part of a single development process. When your documentation is off in
a wiki, that's simply not practical - you need a separate review process
to account for the fact that you can't run a diff on a web service.

In-tree docs also give you a lot more flexibility in the *format* of the 
resulting user docs. The most obviously useful variants that come native 
with sphinx are the ordinary HTML builder and the single-file HTML 
builder, but you can generate other formats like PDF, epub, compiled 
HTML, man pages, QT help files, etc.

I've even heard mutterings of a Sphinx -> DocBook builder, but I don't 
think anyone has actually published such a thing as yet (there *are* 
DocBook -> Sphinx converters, though).

> Plus you have more flexibility on a wiki; sphinx calls itself WYSIWYG
> but it's exactly the opposite of that, whereas with a wiki it's much
> simpler to hit "preview".

I'm not sure where you encountered a claim that Sphinx was WYSIWIG
- ReStructuredText is a markup language and bills itself as such. As
markup languages go, it's a fairly *readable* one, but it's definitely
not WYSIWIG.

However, so long as you have Sphinx installed ("yum install 
python-sphinx" on Fedora) it's actually pretty easy to see the generated 
output from Sphinx while updating the docs locally: by default, 
'sphinx-quickstart' sets up your docs directory so that a simple "make 
html" will give you a browsable copy of your documentation in 
'_build/index.html'

> I'm still willing to look into sphinx, but my early impressions are
> that we're going to have to invest a reasonably large amount of work
> getting it to look at the places in code we want it to look and
> format it for the web site. Ultimately, even if we do, you still have
> to find the template for what our API docs should look like and
> remember to write/update them, so I'm not convinced it's any better
> than the wiki -> user guide process we already have in place.

The really nice thing about Sphinx autodoc is that it's quite granular.
You can start with a placeholder like:

.. automodule:: mymodule
   :members:

And then, over time, fill in the details with handcrafted prose and
reduce the reliance on autogeneration from docstrings.

The docstrings themselves can then be reduced over time to focus more on
*reminders* for interactive use rather than trying to be exhaustive
documentation.

A couple of other Sphinx extensions that I'm quite fond of are
"intersphinx" (which allows you to reference other Sphinx documentation
sets) and "viewcode" (which includes copies of documented source modules
in the generated HTML with direct links from their prose documentation)

You can see all three of these in action on my walkdir project docs, 
which I put together in a few hours last weekend:
    http://walkdir.readthedocs.org

Hit the "Show Source" button in the left nav bar to see how it is all 
put together.

(RTFD is another great feature of the Sphinx ecosystem)

While I've been using Sphinx for years for the Python docs, this was the 
first time I had used it for one of my own projects and I was quite 
impressed with how easy it was to get going.

A new more nice features (either native or readily available via 
extensions):

automatic generation of index pages, for example:
   http://walkdir.readthedocs.org/en/latest/genindex.html
   http://walkdir.readthedocs.org/en/latest/py-modindex.html

make linkcheck:
   Checks your documentation for links to dead URLs

make coverage:
  Tells you which parts of your code aren't covered by your prose 
documentation (although I haven't figured out how to configure this 
extension properly as yet. Somewhat ironically, it isn't fully 
documented...)

blockdiag/seqdiag:
   These are nice, simple text recipe -> SVG/PNG diagram tools. I've 
used blockdiag standalone, but both of these are also usable as sphinx 
plugins:
   http://blockdiag.com/en/blockdiag/index.html
   http://blockdiag.com/en/seqdiag/

> = Conclusion =
 > Is an in-code solution really going to
> make that much of a difference to you when you edit something or
> write a new API?

Yes, yes, a thousand times yes :)

I've done both out-of-tree docs and in-tree docs in the past and I now 
consider out-of-tree docs to be as bad an idea as an out-of-tree test suite.

Cheers,
Nick.

-- 
Nick Coghlan
Red Hat Engineering Operations, Brisbane