Bug#894214: python-debian: Build API documentation

[Stuart Prescott]

Hi again,

> 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/

In the absence of objections or other feedback, I'll merge this branch next 
weekend.

> 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. 

I've done some work in folding separated documentation into the code so that 
the docstrings and the genereated docs are more useful.


> 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!

This problem remains -- some "_hiddden" classes and functions need to be 
included in the API docs to be meaningful at all while others are most 
unwelcome.

Help needed!

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

My feeling is that if the apidocs are useful enough to put on a website, they 
are useful enough to put in a package.

cheers
Stuart

-- 
Stuart Prescott    http://www.nanonanonano.net/   stuart at nanonanonano.net
Debian Developer   http://www.debian.org/         stuart at debian.org
GPG fingerprint    90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7