[docs] Documenting CLI references (openstack-auto-commands)

Andrey Kurilin andr.kurilin at gmail.com
Fri Apr 19 17:20:56 UTC 2019


Hi Seam!

Rally CLI is implemented on top of argparse library. Our CLI looks like
`rally <category> <command>`.
As for documentation, I wrote a sphinx extension for auto-constructing CLI
references.
It contains some rally-specific stuff, but not too much. Maybe, it can be
helpful for you.

Refs:
1) extension itself:
https://github.com/openstack/rally/blob/1.4.1/doc/ext/cli_reference.py
2) place to display cli ref:
https://raw.githubusercontent.com/openstack/rally/1.4.1/doc/source/cli_reference.rst
3) result at rtd: https://rally.readthedocs.io/en/latest/cli_reference.html
4) result at docs.o.o using an old openstack theme -
https://docs.openstack.org/rally/latest/cli_reference.html

пт, 19 апр. 2019 г. в 01:01, Sean McGinnis <sean.mcginnis at gmx.com>:

> Hey everyone,
>
> Hoping someone has discussed this and has a recommended course of action.
>
> Back when we had the awesome support of the openstack-docs team, there was
> a
> command called openstack-auto-commands that would load up client commands
> and
> generate help output for all commands. With the resource constraints that
> hit
> the team, there were less folks to support tools like this. Docs moved into
> each team's repos and, for the most part, I think that has worked out well.
>
> Some of the automatic syncing stopped happening with this move to in-repo
> docs.
> One of them was CLI docs. But it would appear there are at least a few
> teams
> that now have not updated these docs since that move happened several
> releases
> ago:
>
>
> http://codesearch.openstack.org/?q=This%20file%20is%20tool-generated&i=nope&files=&repos=
>
> There are others that appear to have used the last automatically generated
> version and have been (varying degrees of) successful at just manually
> updating
> the doc as things change.
>
> When the tool was removed (https://review.openstack.org/#/c/509402/) it
> was
> stated that it wasn't needed because cliff has sphinx integration to do the
> equivalent automatically. That's all well and good... if you are using
> cliff.
> But I think many of our legacy clients are not.
>
> So looking for recommendations on ways to best keep these docs up to date
> now.
> Migrate to cliff? Other in-repo automation tools?
>
> (and yeah, I know, "drop the CLI and move to openstackclient)
>
> Thanks for any suggestions!
>
> Sean
>
>

-- 
Best regards,
Andrey Kurilin.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20190419/332514b4/attachment-0001.html>


More information about the openstack-discuss mailing list