On Wed, 29 Jul 2026 at 13:57, Daniel P. Berrangé <[email protected]> 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/53b1fdeca932de7b8deffb26eccc9884c6cac065 > > > > > > 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 >
