[Date Prev][Date Next] [Thread Prev][Thread Next]
Re: [Pulp-list] What do you want from an API documentation solution?
- From: Nick Coghlan <ncoghlan redhat com>
- To: pulp-list redhat com
- Subject: Re: [Pulp-list] What do you want from an API documentation solution?
- Date: Tue, 15 Nov 2011 11:51:53 +1000
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
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
(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
automatic generation of index pages, for example:
Checks your documentation for links to dead URLs
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
These are nice, simple text recipe -> SVG/PNG diagram tools. I've
used blockdiag standalone, but both of these are also usable as sphinx
= 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.
Red Hat Engineering Operations, Brisbane
[Date Prev][Date Next] [Thread Prev][Thread Next]