Docs survey feedback: add a "cheatsheet" for the main commands

[acozine]

Summary

Add a page with examples for ansible-playbook and other commonly-used CLI commands, similar to an O'Reilly cookbook. Include lots of options/flags.

• [x] ansible-playbook
• [x] ansible-galaxy
• [ ] ansible
• [ ] ansible-inventory
• [ ] ansible-doc
• [ ] ansible-config
• [ ] ansible-vault
• [ ] ansible-console
• [ ] ansible-pull
• [ ] ansible-test

Issue Type

Documentation Report

Component Name

docs/docsite/cli/

Ansible Version

$ ansible --version
N/A

Configuration

$ ansible-config dump --only-changed
N/A

OS / Environment

N/A

Additional Information

None needed.

Code of Conduct

• [X] I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description: None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[acozine]

For folks who find this issue searching for documentation on the CLI tools, current detailed docs for them are here: https://docs.ansible.com/ansible/latest/user_guide/command_line_tools.html.

The cheatsheet is a good idea, it just hasn't been implemented yet. Check out the DaWGs (Docs Working Group) if you can help!

[IlyesSemlali]

Hi ! I'd like to document the most used ansible commands in the mentionned CheatSheet, can I be assigned on this issue ?

[samccann]

Hey @IlyesSemlali ! So sorry I didn't see this! Are you still up for adding this documentation to the cheatsheet?

[samccann]

This can be one PR per command if you don't want to add all of them.

[Dule-martins]

Hey @acozine creating a PR with a template of the example you point me to, how should I go about getting the cheatsheet for Ansible-galaxy as one of the main commands?

To be sure, should I have created a folder cli to store the docs for other commonly-used CLI commands as mentioned above?

[acozine]

@Dule-martins you can just add the other commands to the existing page in the docs. Take a look at https://github.com/ansible/ansible/pull/76655/files, which added the ansible-playbook command (but be aware, that file has moved . . . see below for the new location).

The complete CLI docs are auto-generated. For example the page https://docs.ansible.com/ansible/latest/cli/ansible-config.html is created from the python code for the ansible-config utility. So there is no file called docs/docsite/rst/cli/ansible-config.rst even though there is a docs page at https://docs.ansible.com/ansible/latest/cli/ansible-config.html.

You can use that docs page as a source of content for adding a section about ansible-config to the cheatsheet file in its new location at https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/command_guide/cheatsheet.rst.

Thanks for taking a look at this!

[samccann]

@Dule-martins hey thanks for taking this on! I just had a thought - as writers, we may not know the common flags etc for each command. What do you and @acozine think about asking for common flags etc on something like the ansible Reddit? They are usually a helpful group of people there and we might get and idea of what people typically do with something like the ansible-galaxy command etc..

[Dule-martins]

@Dule-martins you can just add the other commands to the existing page in the docs. Take a look at https://github.com/ansible/ansible/pull/76655/files, which added the ansible-playbook command (but be aware, that file has moved . . . see below for the new location).

The complete CLI docs are auto-generated. For example the page https://docs.ansible.com/ansible/latest/cli/ansible-config.html is created from the python code for the ansible-config utility. So there is no file called docs/docsite/rst/cli/ansible-config.rst even though there is a docs page at https://docs.ansible.com/ansible/latest/cli/ansible-config.html.

You can use that docs page as a source of content for adding a section about ansible-config to the cheatsheet file in its new location at https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/command_guide/cheatsheet.rst.

Thanks for taking a look at this!

Thank you for helping me understand how to handle this issue.

[Dule-martins]

@Dule-martins hey thanks for taking this on! I just had a thought - as writers, we may not know the common flags etc for each command. What do you and @acozine think about asking for common flags etc on something like the ansible Reddit? They are usually a helpful group of people there and we might get and idea of what people typically do with something like the ansible-galaxy command etc..

I will check that out as I work on this, thank you @samccann

[samccann]

We did ask on reddit here and with a community-topic. So far not so much feedback but hopefully we'll get a few more replies.

[BhattacharjeeSutapa]

Hi I'm interested to start working in this issue. Please assign me.

[oraNod]

@BhattacharjeeSutapa You're all set. Please let us know if you have any questions or need more help for this one.

[mattclay]

@acozine Is there a reason some commands were omitted from the checklist in the summary?

• ansible-console
• ansible-pull
• ansible-test

[samccann]

Updated the description to add those three.. thanks @mattclay

[samccann]

@BhattacharjeeSutapa - let's try taking this one command at a time. The next one on the list is [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html).

From a user perspective, this is used two ways:

• to install a role from galaxy `ansible-galaxy install
• to install a collection from galaxy
• to batch download either of these using a requirements file.
• to list all installed roles or collections

Since this cheatsheet is in the user guide, I'd say we should ignore how developers use this command for now.

So if we follow the cheatsheet for ansible-playbook, then we'd want three simple examples I think:

• ansible-galaxy install <role>
• ansible-galaxy collection <namespace.collection-name>
• ansible-galaxy collection -r requirements.txt

That last one is the only one with a flag and the requirements.txt is a file that lists all the collections the user wants to install at once.

[samccann]

Since we moved docs to a new repo, the cheatsheet rst file is now at https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/command_guide/cheatsheet.rst

[samccann]

For ansible-galaxy - should also include ansible-galaxy role install and ansible-galaxy install -r in a follow up PR.