Bug#894214: python-debian: Build API documentation

[Stuart Prescott]

Source: python-debian
Version: 0.1.32
Severity: wishlist
Tags: patch

Now that python-debian is hosted on salsa, we can do things like run tests
automatically. It's also feasible to build API documentation with sphinx
automatically and for that documentation to be hosted on pages.debian.net.

I've experimented with each of these and created the following work-in-progress
branch to to see what is possible:

https://salsa.debian.org/python-debian-team/python-debian/merge_requests/3

and the genearted documentation can be found at

https://stuart.pages.debian.net/python-debian/

(once merged, that URL would change and would be included in the README file)

Thoughts?

The docstrings aren't great in a lot of places which limits the use of the
API docs without looking at the code too, but we can aim for continuous
improvement in that regard. The autodoc API documentation needs to learn not
to pick up some private members that are uninteresting while we need to keep
others present since they are base classes and the only documentation for some
subclasses is within those base classes. The input of those with more sphinx
experience would be great about now!

Is it worth putting these files into a new python-debian-doc binary package?

cheers
Stuart