internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-08 14:22:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

generate rst doc pages for command line tools (#27530)

Browse Source 
* 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
6e34ea6242 and
a3afc78535

* 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>`
This commit is contained in:
Adrian Likins
2017-09-07 15:44:20 -04:00
committed by GitHub
parent 4a73390823
commit 89c973445c
9 changed files with 404 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/templates/man.j2 vendored
View File

@@ -20,8 +20,17 @@ SYNOPSIS
DESCRIPTION
-----------
*{{name}}* {{ long_desc|default('', True)|wordwrap }}
{{ long_desc|default('', True)|wordwrap }}
{% if options %}
COMMON OPTIONS
--------------
{% for option in options|sort(attribute='options') %}
{% 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
@@ -38,22 +47,19 @@ ARGUMENTS
{% if actions %}
ACTIONS
-------
{% for action in actions %}
{{ action }}
*{{ action }}*::: {{ (actions[action]['desc']|default(' '))|wordwrap}}
{{ (actions[action]|default(' '))|wordwrap}}
{% if actions[action]['options'] %}
{% for option in actions[action]['options']|sort %}
{% 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 %}
OPTIONS
-------
{% for option in options|sort(attribute='options') %}
{% for switch in option['options'] %}*{{switch}}* {% if option['arg'] %}'{{option['arg']}}'{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}::
{{ option['desc'] }}
{% endfor %}
{% endif %}
{% if inventory %}
INVENTORY
@@ -111,7 +117,7 @@ Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
{% for other in cli_list|sort %}{% if other != cli %}*ansible{% if other != 'adhoc' %}-{{other}}{% endif %}*(1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %}
{% for other in cli_list|sort %}{% if other != cli %}*ansible{% if other != 'adhoc' %}-{{other}}{% endif %}*(1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %}
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>.