Add authctl docs

[adombeck]

Important

This is based on #1087

Generate authctl docs via cobra.

UDENG-8760

[adombeck]

@edibotopic do you understand why the build of the docs fails in the CI but not when I build it locally via make html? The command-line options passed to sphinx seem to be about the same.

In the CI I these warnings which I assume are the reason the build fails:

/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_group.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_group_set-gid.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user_lock.md.rst:1: WARNING: Document headings start at H2, not H1
looking for now-outdated files... /home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user_set-uid.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user_unlock.md.rst:1: WARNING: Document headings start at H2, not H1

I don't see those locally.

[adombeck]

In the CI I these warnings which I assume are the reason the build fails:

FTR, we were able to resolve that - @edibotopic figured out how to ignore these warnings

[edibotopic]

FTR, we were able to resolve that - @edibotopic figured out how to ignore these warnings

Thanks @adombeck .

I think it's OK to ignore these warnings for now so that we are better able to support users with these docs. In the long run, we should fix the header levels so that they conform with the rest of the docs.

In future, we can work on improving the doc generation and formatting of the rendered output, depending on capacity, etc.

[adombeck]

@edibotopic I think this is now ready for an initial review. Please ignore all the commits which are not touching the documentation, those are from #1087.

The documentation is very rudimentary for now, we might want to write a more extensive overview of authctl and maybe inline the documentation of the separate commands in the index.md. As discussed on MM, we might also want to use gencodo to improve the generated markdown.

[adombeck]

we might also want to use gencodo to improve the generated markdown.

For later reference, I pushed a WIP commit which uses gencodo to https://github.com/adombeck/authd/tree/authctl-docs-gencodo

[edibotopic]

Excellent work @adombeck .

I've left a few minor suggestions and comments.

Some of the more elaborate synopses tend to push the basic usage example (Use) quite far down, and visually pair it with a separate command, example:

I think that's probably just a limitation of the native Cobra docgen, but it's something we can look at in future.

[adombeck]

Some of the more elaborate synopses tend to push the basic usage example (Use) quite far down, and visually pair it with a separate command

Yeah, that also annoyed me. I think the description just doesn't belong in the "Synopsis" section. My understanding of a "Synopsis" is that it's only the formal description of how to run the command what command line options it takes (like authctl user lock <user> [flags]). In my opinion the description should go in a separate section, like in man pages. I already opened a PR upstream to change that: spf13/cobra#2344

This is an issue which we could fix with gencodo.

[edibotopic]

Some of the more elaborate synopses tend to push the basic usage example (Use) quite far down, and visually pair it with a separate command

Yeah, that also annoyed me.
[...]
This is an issue which we could fix with gencodo.

Thanks for the context @adombeck . I agree, let's wait for gencodo. It's OK for now.

[edibotopic]

Great work! Nice to have this in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 85.86%. Comparing base (7dd4884) to head (0f1e87b).
⚠️ Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/authctl/root/root.go	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1179      +/-   ##
==========================================
- Coverage   85.99%   85.86%   -0.14%     
==========================================
  Files          98       99       +1     
  Lines        6685     6685              
  Branches      111      111              
==========================================
- Hits         5749     5740       -9     
- Misses        880      888       +8     
- Partials       56       57       +1     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.