[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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

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

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

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

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:

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:

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...)

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:

= 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.


Nick Coghlan
Red Hat Engineering Operations, Brisbane

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]