[libvirt] libvirt Application Development Guide - revival

[Laine Stump]

On 06/06/2012 07:25 PM, Scott Radvan wrote:
> Hi list,
>
>
> I write virtualization docs for Red Hat and would like to maintain this
> guide[1] - it's in need of a bit of attention.


Very kindly understated :-)


> I have publican and the publican brand up and running, and have already
> cloned the git repo, but I would appreciate some help on how to get
> commit access

I'm not sure who has the ability to grant commit access (definitely DV
and danpb), but that's a detail easily figured out. More importantly
everyone should agree on the review process. For other libvirt
"sub-projects", when someone wants to propose a change, they do a local
git commit, then use

   git send-email --$patch-count --to="libvirt-list at redhat.com"
                  --subject-prefix="$subproject-name PATCH"

to send the patch to libvir-list. Once someone has responded with ACK,
it can then be pushed to the repo (either by the author, or if they
don't have push privileges, then by someone else who does).

The alternative for documentation could be to just allow pushing, then
periodically review it, but that sounds like a recipe for
procrastination on the part of reviewers :-)

> or any other pertinent info I should be aware of before
> getting started.

Something you may find useful as a source for new "basic" content - all
libvirt API functions are documented with special comments within
src/libvirt.c and include/libvirt/libvirt.h (after being massaged around
by a python script called apibuild.py) end up at:

   http://libvirt.org/html/libvirt-libvirt.html

Similarly (but with less post-processing), any time someone adds
something to libvirt that expands the XML used by one of the public
APIs, the reviewers on the list require that the files in libvirt's
docs/*.html.in are updated to reflect the new XML, and this eventually
shows up online at

  http://libvirt.org/format.html

Click on the headers under "XML format" at the left to get the
individual pages, e.g.:

  http://libvirt.org/formatdomain.html

Between those two pieces, you have a (hopefully) complete libvirt API
Reference, and watching for commits to those files will alert you that
you need to update the developer's guide.

An important fact about libvirt is that, although certain portions of
the API may be deprecated, we guarantee that once something is in the
API, it will remain, and it will continue to work.

Related to that, you will notice that any time something is added to the
documentation of libvirt's XML, it has a <since> tag associated with it
which documents what version of libvirt first supported that particular
feature. If you assume that user's of the developer's guide could be
using any version of libvirt, you would want that information noted in
the guide. On the other hand, there is a lot of stuff that was added
quite a long time ago, and adding in all those tags could just begin to
cloud up the real information - do we want a cut-off version before
which we document the feature as being there effectively "forever"?

>
> Any comments on the guide (ideas for new sections, future trends for
> libvirt app development, parts that are plain wrong) would be more than
> welcome!

Well, since the entire API is already documented (although the XML is
documented separately from the functions that use it, which is a bit
cumbersome and should probably be addressed as well), I think the idea
for the developer's guide was to give a brief higher level overview of
each section of the API, followed by some actual examples. Beyond the
examples that stick to a single area, it might be nice to have some
larger examples that use different parts of the API simultaneously to do
something useful.

(An odd idea just came to my mind: the examples I noticed were in C; I
wonder how difficult it would be to construct the manual so that it
could easily be generated with the examples in python, perl, java, ruby,
etc. instead. Knowing nothing about Publican, I have no idea.)


>
> A Red Hat Bugzilla component is set up for this guide:
>
> doc-Libvirt_Application_Development_Guide (under the Red Hat Enterprise
> Linux 6 product).

Actually there is also an upstream component setup for it under
Community / Virtualization Tools / libvirt-appdev-guide. That would be
the appropriate place to enter and track problems with the content in
the libvirt.org git repo. Once a snapshot of that is taken for RHEL,
problems with the particular RHEL release version of the guide should be
tracked in the RHEL6 component.


> Thanks for your help,

I think we stand to benefit at least as much as you :-) The Developer's
Guide was semi-abandoned a couple years ago because nobody had the time
to work on it; many chapters are just empty "TBD" placeholders, and much
of the rest is out of date.