diff options
author | Adrian Likins <alikins@redhat.com> | 2017-09-07 15:44:20 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-09-07 15:44:20 -0400 |
commit | 89c973445c6bbb08551703917a4eec6e484a3e0c (patch) | |
tree | 44b97c2d3d83b47cffd0e22cea3f033accc79e07 /docs/templates/cli_rst.j2 | |
parent | 4a73390823bfe0f1bc6c1a548bb77e9af07e4673 (diff) | |
download | ansible-89c973445c6bbb08551703917a4eec6e484a3e0c.tar.gz |
generate rst doc pages for command line tools (#27530)
* let generate_man also gen rst pages for cli tools
* make template-file, output-dir, output format cli options for generate_man
* update main Makefile to use generate_man.py for docs (man pages and rst)
* update vault docs that use :option:
* Edits based on
https://github.com/alikins/ansible/commit/6e34ea62429c417939bd96b6de5bf7e6ab1ff765 and
https://github.com/alikins/ansible/commit/a3afc785357878da354e21a709cf3b9f16c3f146
* add a optparse 'desc' to lib/ansible/cli/config.py
The man page needs a short desc for the 'NAME' field
which it gets from the option parse 'desc' value.
Fixes building ansible-config man page.
* add trim_docstring from pep257 to generate_man
use pep258 docstring trim function to fix up any indention
weirdness inherit to doc strings (ie, lines other than
first line being indented.
* Add refs to cli command actions
To reference ansible-vaults --vault-id option, use:
:option:`The link text here <ansible-vault --vault-id>`
or:
:option:`--vault-id <ansible-vault --vault-id>`
To reference ansible-vault's 'encrypt' action, use:
:ref:`The link text here <ansible_vault_encrypt>`
or most of the time:
:ref:`ansible-vault encrypt <ansible_vault_encrypt>`
Diffstat (limited to 'docs/templates/cli_rst.j2')
-rw-r--r-- | docs/templates/cli_rst.j2 | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/docs/templates/cli_rst.j2 b/docs/templates/cli_rst.j2 new file mode 100644 index 0000000000..15ca2b3461 --- /dev/null +++ b/docs/templates/cli_rst.j2 @@ -0,0 +1,139 @@ +{% set name = cli_name -%} +{% set name_slug = cli_name -%} + +.. _{{name}}: + +{% set name_len = name|length + 0-%} +{{ '=' * name_len }} +{{name}} +{{ '=' * name_len }} + + +:strong:`{{short_desc|default('')}}` + + +.. contents:: + :local: + :depth: 2 + + +.. program:: {{cli_name}} + +Synopsis +======== + +.. code-block:: bash + + {{ usage|replace('%prog', cli_name) }} + + +Description +=========== + + +{{ long_desc|default('', True) }} + +{% if options %} +Common Options +============== + + +{% for option in options|sort(attribute='options') %} + +.. option:: {% for switch in option['options'] %}{{switch}}{% if option['arg'] %} <{{option['arg']}}>{% endif %}{% if not loop.last %}, {% endif %}{% endfor %} + + {{ option['desc'] }} +{% endfor %} +{% endif %} + +{% if arguments %} +ARGUMENTS +========= + +.. program:: {{cli_name}} + +{% for arg in arguments %} +.. option:: {{ arg }} + + {{ (arguments[arg]|default(' '))}} + +{% endfor %} +{% endif %} + +{% if actions %} +Actions +======= + +{% for action in actions %} + +.. program:: {{cli_name}} {{action}} +.. _{{cli_name|replace('-','_')}}_{{action}}: + +{{ action}} +{{ '-' * action|length}} + +{{ (actions[action]['desc']|default(' '))}} + +{% if actions[action]['options'] %} + + +{% for option in actions[action]['options']|sort %} +.. option:: {% for switch in option['options'] if switch in actions[action]['option_names'] %}{{switch}} {% if option['arg'] %} <{{option['arg']}}>{% endif %}{% if not loop.last %}, {% endif %}{% endfor %} + + {{ (option['desc']) }} +{% endfor %} +{% endif %} + +{% endfor %} +.. program:: {{cli_name}} +{% endif %} + +Environment +=========== + +The following environment variables may be specified. + +{% if inventory %} +:envvar:`ANSIBLE_INVENTORY` -- Override the default ansible inventory file + +{% endif %} +{% if library %} +:envvar:`ANSIBLE_LIBRARY` -- Override the default ansible module library path + +{% endif %} +:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file + +Many more are available for most options in ansible.cfg + + +Files +===== + +{% if inventory %} +:file:`/etc/ansible/hosts` -- Default inventory file + +{% endif %} +:file:`/etc/ansible/ansible.cfg` -- Config file, used if present + +:file:`~/.ansible.cfg` -- User config file, overrides the default config if present + +Author +====== + +Ansible was originally written by Michael DeHaan. + +See the `AUTHORS` file for a complete list of contributors. + + +Copyright +========= + +Copyright © 2017 Red Hat, Inc | Ansible. + +Ansible is released under the terms of the GPLv3 License. + +See also +======== + +{% for other in cli_bin_name_list|sort %}:manpage:`{{other}}(1)`, {% endfor %} + |