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

[Jay Dobies]

Ok, Nick sold me on looking more deeply into sphinx as a more permanent 
solution. I don't think I'll get it in place in time to use it this 
sprint, so keep at the current process and once we get the 
infrastructure in place we can revisit and migrate all the docs into the 
codebase.

On 11/14/2011 08:51 PM, Nick Coghlan wrote:
> 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.
>


-- 
Jay Dobies
Freenode: jdob @ #pulp
http://pulpproject.org | http://blog.pulpproject.org