[docs] Documenting CLI references (openstack-auto-commands)
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
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_refer... 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@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.
On Fri, Apr 19, 2019 at 08:20:56PM +0300, Andrey Kurilin wrote:
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_refer... 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
This looks very useful. Thanks Andrey!
participants (2)
-
Andrey Kurilin
-
Sean McGinnis