691c8e8603
Since man pages aren't accessible to users after a `pip install`, there's no need to include them in the sdist. This change makes it trivial to build man pages from source, which makes them much easier to iterate on. It also simplifies creation and testing of the sdist, since it no longer requires building man pages. The new `packaging/cli-doc/build.py` script can generate both man pages and RST documentation. This supports inclusion on the docs site without a dependency on `ansible-core` internals. Having a single implementation for both simplifies keeping the two formats in sync.
153 lines
3.1 KiB
Django/Jinja
153 lines
3.1 KiB
Django/Jinja
{%- set heading = ['-', '+', '#', '*', '^', '"', "'"] -%}
|
|
{% macro render_action(parent, action, action_docs) %}
|
|
|
|
.. program:: {{cli_name}} {{parent + action}}
|
|
.. _{{cli_name|replace('-','_')}}_{{parent|replace(' ','_')}}{{action}}:
|
|
|
|
{{ parent + action }}
|
|
{{ heading[parent.count(' ')] * (parent + action)|length }}
|
|
|
|
{{ (action_docs['desc']|default(' ')) }}
|
|
|
|
{% if action_docs['options'] %}
|
|
|
|
|
|
{% for option in action_docs['options']|sort(attribute='options') %}
|
|
.. option:: {% for switch in option['options'] if switch in action_docs['option_names'] %}{{switch}} {% if option['arg'] %} <{{option['arg']}}>{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}
|
|
|
|
{{ (option['desc']) }}
|
|
{% endfor %}
|
|
{% endif %}
|
|
{%- set nested_actions = action_docs['actions'] -%}
|
|
{% if nested_actions %}
|
|
|
|
{% for nested_action in nested_actions %}
|
|
{{ render_action(parent + action + ' ', nested_action, nested_actions[nested_action]) }}
|
|
|
|
{% endfor %}
|
|
{%- endif %}
|
|
{%- endmacro -%}
|
|
:source: {{ source }}
|
|
|
|
{% 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: {{content_depth}}
|
|
|
|
|
|
.. 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') if option.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 %}
|
|
{{- render_action('', action, actions[action]) }}
|
|
|
|
|
|
|
|
{% 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.
|
|
|
|
|
|
License
|
|
=======
|
|
|
|
Ansible is released under the terms of the GPLv3+ License.
|
|
|
|
See also
|
|
========
|
|
|
|
{% for other in cli_bin_name_list|sort %}{% if other != cli_name %}:manpage:`{{other}}(1)`{% if not loop.last %}, {% endif %}{% endif %}{% endfor %}
|