Generate CLI documentation using sphinx with autoprogram

[jonrebm]

This is a second try after the formatting in #1707 using sphinx-argparse did not satisfy.

Manage the documentation with sphinx and auto-document labgrid-client arguments and subcommands from source using sphinx autoprogram.

Sections from the original man/labgrid-client.rst which are not obsoleted by the autogenerated reference are migrated into the argparse structure. Sphinx generates both the manpages as well as their html documentation counterpart.

I believe the result of this is much more useful than the current manpages we have that just don't sufficiently document usage of the subcommands.

See the readthedocs builds for results.

[jonrebm]

• Rebased onto master integrating the manpage changes that happened in the meantime
• Updated to keep tracking generated troff manpages as suggested by @Bastian-Krause in Generate labgrid-client subcommand and option documentation from argparse #1707 (comment)
• Formatted to pass "Format with ruff" in CI.

Ready to merge as far as I can tell

[Emantor]

I like this version a lot better than the previous argparse version, nice work.

[codecov]

Codecov Report

❌ Patch coverage is 15.25424% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 45.2%. Comparing base (f63dfd7) to head (45ae505).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
labgrid/remote/client.py	15.2%	50 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #1767     +/-   ##
========================================
- Coverage    45.3%   45.2%   -0.1%     
========================================
  Files         172     172             
  Lines       13517   13556     +39     
========================================
+ Hits         6130    6138      +8     
- Misses       7387    7418     +31     

Flag	Coverage Δ
3.10	45.2% <15.2%> (-0.1%)	⬇️
3.11	45.2% <15.2%> (-0.1%)	⬇️
3.12	45.2% <15.2%> (-0.1%)	⬇️
3.13	45.2% <15.2%> (-0.1%)	⬇️
3.14	45.2% <15.2%> (-0.1%)	⬇️
3.9	45.3% <15.2%> (-0.1%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jonrebm]

Thank you, happy to hear @Emantor
Now that I have your attention. There is a little oddity that the manpages used to have different authorship and copyright texts compared to the sphinx doc. I assumed this to be circumstantial and made no attempts to keep this.
Hence, this:

labgrid/man/labgrid-coordinator.1

Lines 59 to 68 in f63dfd7

	.SH AUTHOR
	Rouven Czerwinski <[email protected]>
	Organization: Labgrid-Project
	.SH COPYRIGHT
	Copyright (C) 2016-2025 Pengutronix. This library is free software;
	you can redistribute it and/or modify it under the terms of the GNU
	Lesser General Public License as published by the Free Software
	Foundation; either version 2.1 of the License, or (at your option)
	any later version.

Changed into this:

labgrid/man/labgrid-coordinator.1

Lines 60 to 63 in 3bcbc26

	.SH AUTHOR
	Jan Luebbe, Rouven Czerwinski
	.SH COPYRIGHT
	2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski

Due to this:

labgrid/doc/conf.py

Lines 59 to 61 in f63dfd7

	project = 'labgrid'
	copyright = '2016-2025 Pengutronix, Jan Luebbe and Rouven Czerwinski'
	author = 'Jan Luebbe, Rouven Czerwinski'

Can it stay this way or should the LGPL be explicitly mentioned here?
Why no mention of "the labgrid contributers" by the way? 🙂

[Emantor]

I don't think an explicit mention of LGPL is necessary here and I am also fine if we extend the authors with "and contributors".

[jonrebm]

Okay, thanks.

Not ready for merge just yet. CI is using a different version of sphinx than what I used to generate them. This is most likely the reason why it outputs manpages with a slightly different formattingin some of the pipleines (and CI is configured to guarantee manpages are generated as tracked).

[Bastian-Krause]

Nice, this is so much better!

I haven't looked through this thoroughly, but I noticed that positional arguments are currently indistinguishable from sub commands in "usage", e.g.

• https://labgrid--1767.org.readthedocs.build/en/1767/man/client.html#labgrid-client-allow
• https://labgrid--1767.org.readthedocs.build/en/1767/man/client.html#labgrid-client-add-alias

[jonrebm]

Nice, this is so much better!

Happy to hear!

I haven't looked through this thoroughly, but I noticed that positional arguments are currently indistinguishable from sub commands in "usage", e.g.

* https://labgrid--1767.org.readthedocs.build/en/1767/man/client.html#labgrid-client-allow

* https://labgrid--1767.org.readthedocs.build/en/1767/man/client.html#labgrid-client-add-alias

autoprogram will exactly print the usage line as generated by argparse, we have (and had) the same ambiguity when usage is shown via e.g. labgrid-client allow -h. I'm not sure why argparse displays it this way but it's out of scope for this pr.

[Bastian-Krause]

Nice work overall. The argparse autoprogram integration needs some work, but I think this is definetely the way forward. See comments below.

I don't think we should keep the "labgrid-pytest" man page: labgrid ships a pytest plugin, that's all. It is documented. The "labgrid-pytest" wrapper is merely a way to install a labgrid + pytest combination in labgrid's Debian integration. Most people will be confused about a "labgrid-pytest" script unavailable to them.

[jonrebm]

Yes, the manpage generation specific argparse code doesn't have test coverage, I hope we can make an exception here.

[Bastian-Krause]

Pushed changes (first as fixups, then squashed):

• renamed for_manpage -> auto_doc_mode, switched default to False, autoprogram now calls labgrid.remote.client:get_parser(auto_doc_mode=True)
• replaced monkey-patched _SubParsersAction.add_parser() with _ActionWrapper class
• don't show range in choices generically
• hide Debian-internal labgrid-pytest in documentation, but still generate man page (same behavior as before)

Edit: This change does not touch the generated man/HTML output, except for labgrid-pytest.

[Bastian-Krause]

Yes, the manpage generation specific argparse code doesn't have test coverage, I hope we can make an exception here.

Don't worry, that check is not required.

[jonrebm]

Thank you and looks good to me

[jonrebm]

Taking a final look at the result, let's lower text width for usage texts to 80 after all.
I set it to 180 as I thought man and the html would wrap that themselves but the html doesn't, adding a horizontal scrollbar and for the manpages too it looks better and seems commonplace to wrap these to around 80

[jonrebm]

Yes looks much better with os.environ["COLUMNS"] = "80", and that's the only change I made.