docs: include generated documentation for the CLI commands

[renanrodrigo]

Why is this needed?

This PR solves all of our problems because now we have a CLI reference, and it is generated from the actual source code.

Test Steps

check the docs

---

• (un)check this to re-run the checklist action

[renanrodrigo]

Readthedocs is complaining about my indentation... @s-makin would you know why? How to fix that, if needed?

Besides that, there are two words (customizable, artifacts) which are in American, and if I translate those to English it becomes inconsistent with all messages in the client itself hahahaha :( so I added them to the wordlist. Do we prefer this small inconsistency in the docs, or in the client itself? OR should we rewrite the whole client in British?

[renanrodrigo]

(I could remove the attach config example completely from the command description, and reformat the security status list of items to use * instead of - - just saying)

[s-makin]

Readthedocs is complaining about my indentation... @s-makin would you know why? How to fix that, if needed?

Besides that, there are two words (customizable, artifacts) which are in American, and if I translate those to English it becomes inconsistent with all messages in the client itself hahahaha :( so I added them to the wordlist. Do we prefer this small inconsistency in the docs, or in the client itself? OR should we rewrite the whole client in British?

Re: the spelling inconsistency, I think since it's coming from the source code it's better for us to just add those spelling exceptions than to start refactoring the codebase into GB English 😬

[s-makin]

Some comments/suggestions - hopefully I've caught all the places that could be causing build issues on RTD, but if not, double check that all your bullet/numbered/unnumbered lists have an empty line before and after, and that anything you want rendered as a code block has a .. code-block:: directive. That should fix the errors you saw :) I can do a check of the rendering after the RTD builds properly.

[renanrodrigo]

Breaks: autogenerated CLI documentation is unformatted

[renanrodrigo]

@s-makin addressed all comments according to what we spoke about. All good with the RTD build now. Please take another look when possible.

[s-makin]

Few more little nits to make the rendering consistent.

Also, there's a broken link to the IRC channel somewhere. I tested the link and it does appear to just hang forever and doesn't even time out. Not sure why?

[orndorffgrant]

I would like to eventually see a table of cli flags with descriptions for each command (example), but that can be a future iteration. This is already a great improvement thank you!

[renanrodrigo]

@orndorffgrant I like the suggestion and I could easily add it now. Not doing because it would look horrible :D
We need to sort out the formatting thing first, and then we gain some... flexibility? Will add this to the backlog after this change lands.

[renanrodrigo]

Breaks: autogenerated CLI reference could include flags and options in the output

[renanrodrigo]

@s-makin addressed all your points, please take another look

[s-makin]

Just one final nitpick to make the bullet lists consistently formatted.

Ideally, I would also like to see some brief instructions on how the autogeneration works in the devdocs (where the autogeneration happens, what files to change, etc). Since we know we'll have follow-up work on this, and we know it won't be imminently, it would be good to have that documented for Future Us. I'd be ok with us including that in a separate PR, though, if we don't want to hold this one up.

[dheyay]

lgtm except some remaining minor nits from @s-makin

[renanrodrigo]

@s-makin last review addressed, I can type the instructions on generating the content in this PR here. I see that there is also no dev docs for the autogenerated API commands, and both of those would be important for the release process. I vote for merging this one (together with #3282 for the sake of mergeness, and then I'll open a separate one (soon) including instructions on how to use these tools to make sure everything is up to date prior to releasing.

[s-makin]

I vote for merging this one (together with #3282 for the sake of mergeness, and then I'll open a separate one (soon) including instructions on how to use these tools to make sure everything is up to date prior to releasing.

Sounds good to me :) let's do that

[s-makin]

Thanks for all the work on this!

[renanrodrigo]

Hmm the breaks thing didn't trigger because merging to docs
I'll raise the issues by hand in a while