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

[Stuart Prescott]

Hi again,

Post by Stuart Prescott
I've experimented with each of these and created the following
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.

Post by Stuart Prescott
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.

Post by Stuart Prescott
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!

Post by Stuart Prescott
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

[Debian Bug Tracking System]

tag -1 pending

Bug #894214 [src:python-debian] python-debian: Build API documentation
Added tag(s) pending.

[Stuart Prescott]

… And now merged, with API documentation now published automatically at

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

Post by Stuart Prescott

Post by Stuart Prescott
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!

Post by Stuart Prescott
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.

regards
Stuart

[Debian Bug Tracking System]

Your message dated Sun, 19 Aug 2018 10:48:55 +0000
with message-id <E1frLGR-0007X2-***@fasolo.debian.org>
and subject line Bug#894214: fixed in python-debian 0.1.33
has caused the Debian Bug report #894214,
regarding python-debian: Build API documentation
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ***@bugs.debian.org
immediately.)