[libvirt-python] RFC: Adding Sphinx API documentation for Python bindings
Hi, I'd like to propose adding generated API documentation for the libvirt-python bindings and would appreciate the community's opinion on whether this is worthwhile. The problem: The libvirt-python bindings currently have no browsable API documentation. Users who want to discover available methods, their parameters, or behavior have to either read the C API docs and map them to Python or inspect the generated libvirt.py source directly, or rely on IDE auto-completion. But in the same time the infrastructure to produce good documentation is already in place, I mean XML API descriptions libvirt-api.xml, generator.py and override files (libvirt-override-virDomain.py, etc.) also contain docstrings. These docstrings are present but are not rendered anywhere for users to browse. The proposal: Add a minimal Sphinx setup (docs/conf.py, a few .rst files, and a requirements-docs.txt) to generate HTML API reference from the existing docstrings. This would cover all four modules: libvirt, libvirt_qemu, libvirt_lxc, and libvirtaio. This is a working prototype that builds successfully and produces complete API reference pages. https://gitlab.com/rsmigiel/libvirt-python/-/commit/53b1fdeca932de7b8deffb26... Would this be a welcome change? Any concerns or suggestions on the approach? Thanks for your feedback! ---------------------- < Tℏanks | Radek >
On Wed, Jul 22, 2026 at 09:42:32AM +0200, Radoslaw Smigielski via Devel wrote:
Hi, I'd like to propose adding generated API documentation for the libvirt-python bindings and would appreciate the community's opinion on whether this is worthwhile.
The problem: The libvirt-python bindings currently have no browsable API documentation. Users who want to discover available methods, their parameters, or behavior have to either read the C API docs and map them to Python or inspect the generated libvirt.py source directly, or rely on IDE auto-completion.
But in the same time the infrastructure to produce good documentation is already in place, I mean XML API descriptions libvirt-api.xml, generator.py and override files (libvirt-override-virDomain.py, etc.) also contain docstrings. These docstrings are present but are not rendered anywhere for users to browse.
The proposal: Add a minimal Sphinx setup (docs/conf.py, a few .rst files, and a requirements-docs.txt) to generate HTML API reference from the existing docstrings. This would cover all four modules: libvirt, libvirt_qemu, libvirt_lxc, and libvirtaio.
This is a working prototype that builds successfully and produces complete API reference pages. https://gitlab.com/rsmigiel/libvirt-python/-/commit/53b1fdeca932de7b8deffb26...
Would this be a welcome change? Any concerns or suggestions on the approach?
Can you send a merge request proposal, that integrates with GitLab Pages CI jobs, so we can see the full result. With regards, Daniel -- |: https://berrange.com ~~ https://hachyderm.io/@berrange :| |: https://libvirt.org ~~ https://entangle-photo.org :| |: https://pixelfed.art/berrange ~~ https://fstop138.berrange.com :|
On Wed, 29 Jul 2026 at 13:57, Daniel P. Berrangé <berrange@redhat.com> wrote:
On Wed, Jul 22, 2026 at 09:42:32AM +0200, Radoslaw Smigielski via Devel wrote:
Hi, I'd like to propose adding generated API documentation for the libvirt-python bindings and would appreciate the community's opinion on whether this is worthwhile.
The problem: The libvirt-python bindings currently have no browsable API documentation. Users who want to discover available methods, their parameters, or behavior have to either read the C API docs and map them to Python or inspect the generated libvirt.py source directly, or rely on IDE auto-completion.
But in the same time the infrastructure to produce good documentation is already in place, I mean XML API descriptions libvirt-api.xml, generator.py and override files (libvirt-override-virDomain.py, etc.) also contain docstrings. These docstrings are present but are not rendered anywhere for users to browse.
The proposal: Add a minimal Sphinx setup (docs/conf.py, a few .rst files, and a requirements-docs.txt) to generate HTML API reference from the existing docstrings. This would cover all four modules: libvirt, libvirt_qemu, libvirt_lxc, and libvirtaio.
This is a working prototype that builds successfully and produces complete API reference pages. https://gitlab.com/rsmigiel/libvirt-python/-/commit/53b1fdeca932de7b8deffb26...
Would this be a welcome change? Any concerns or suggestions on the approach?
Can you send a merge request proposal, that integrates with GitLab Pages CI jobs, so we can see the full result.
With regards, Daniel -- |: https://berrange.com ~~ https://hachyderm.io/@berrange :| |: https://libvirt.org ~~ https://entangle-photo.org :| |: https://pixelfed.art/berrange ~~ https://fstop138.berrange.com :|
Here is a draft of the review https://gitlab.com/libvirt/libvirt-python/-/merge_requests/210 It produces py_api_docs archive with the Sphinx produced documentation. There are 10 places where the documentation formatting is not _perfect_, this is due to fact that some docs from C API descriptions are not always valid reStructured text, this is handled now in docs/conf.py _needs_literal_docstring() These issues could be fixed separately in the libvirt repo. ---------------------- < Tℏanks | Radek >
participants (2)
-
Daniel P. Berrangé -
Radoslaw Smigielski