mirror of https://github.com/ansible/ansible.git
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 onpull/29940/head6e34ea6242
anda3afc78535
* 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>` (cherry picked from commit89c973445c
)
parent
66a244facc
commit
51949fdeec
@ -0,0 +1,15 @@
|
||||
Command Line Tools
|
||||
==================
|
||||
|
||||
|
||||
.. toctree:: :maxdepth: 1
|
||||
|
||||
ansible
|
||||
ansible-playbook
|
||||
ansible-vault
|
||||
ansible-galaxy
|
||||
ansible-console
|
||||
ansible-config
|
||||
ansible-doc
|
||||
ansible-inventory
|
||||
ansible-pull
|
@ -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 %}
|
||||
|
Loading…
Reference in New Issue