Re: [Qemu-devel] Exploring Sphinx, autodoc, apidoc, and coverage tools for python/qemu

[John Snow <jsnow@redhat.com>]

On 7/25/19 5:02 AM, Peter Maydell wrote:
> On Wed, 24 Jul 2019 at 22:06, John Snow <jsnow@redhat.com> wrote:
>> And then you can edit e.g. the top-level index.rst TOC in docs/index.rst
>> to look like this:
>>
>> ```
>> .. toctree::
>>    :maxdepth: 2
>>    :caption: Contents:
>>
>>    interop/index
>>    devel/index
>>    specs/index
>>    modules
>> ```
> 
> This is obviously just prototyping, but you don't want to put
> anything new in this top level index.rst -- it's only used
> for by-hand full-tree docs builds. Builds from the makefile
> rules will just build our separate manuals (interop, devel,
> specs) separately. You want to put your new documentation into
> whichever manual is best suited (probably devel/, but possibly
> interop/ in some cases?)
> 

Yes, understood -- I was prototyping in a "fresh" / empty repository, so
I was keeping the instructions reasonably comparable to what
sphinx-quickstart might produce if people wanted to explore this outside
of the complexity of the QEMU tree.

If the experiment had gone better, I'd have wanted to either model this
as a Developer sub-manual, or a new top-level manual under "Python
Library" or some such.

(It's hard to say which the QMP library is: it WAS internal developer
tooling, but I'm prototyping turning qmp-shell into something that could
be considered a reference implementation for interop that non-developers
might have a genuine interest in using for non-libvirt scenarios.)

> (Will read the rest of this email later.)
> 

TLDR: I wanted to document for the mailing list that Autodoc seems to
have some shortcomings that doesn't make it very attractive for
documenting our python utilities in a rigorous way.

One of the benefits, in my mind, of using doc generation utilities for
documenting API is the ability to fail the build when the documentation
has observable omissions/mistakes.

Autodoc doesn't seem capable of providing that; though it still may be
more useful than nothing.

--js

> thanks
> -- PMM
>