cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Improve config.rst formatting (#72354) (#72487)

Browse source 
* Indent Jinja2 directives.

* Show version_added and deprecations for ini settings and environment variables.

* Make default conditional, add choices. Copied from #55474.

* Add Ansible variables. Copied from #55474.

* Turn ini keys and environment variables into lists. Copied from #55474.

* Improve formatting. Copied from #55474.

(cherry picked from commit 569d937df8)
This commit is contained in:
Felix Fontein 2020-11-13 21:31:32 +01:00 committed by GitHub
parent cfa8075537
commit fc4411adcd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 107 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

133
docs/templates/config.rst.j2 vendored
View file

@ -1,9 +1,9 @@
.. _ansible_configuration_settings: .. _ansible_configuration_settings:
{% set name = 'Ansible Configuration Settings' -%} {% set name = 'Ansible Configuration Settings' -%}
{% set name_slug = 'config' -%} {% set name_slug = 'config' -%}
{% set name_len = name|length + 0-%} {% set name_len = name|length + 0-%}
{{ '=' * name_len }} {{ '=' * name_len }}
{{name}} {{name}}
{{ '=' * name_len }} {{ '=' * name_len }}
@ -95,40 +95,98 @@ you can use the command line utility mentioned above (`ansible-config`) to brows
{% if config_options %} {% if config_options %}
{% for config_option in config_options|sort %} {% for config_option in config_options|sort %}
{% set config_len = config_option|length -%} {% set config_len = config_option|length -%}
{% set config = config_options[config_option] %} {% set config = config_options[config_option] %}
.. _{{config_option}}: .. _{{config_option}}:
{{config_option}} {{config_option}}
{{ '-' * config_len }} {{ '-' * config_len }}
{% if config['description'] and config['description'] != [''] %} {% if config['description'] and config['description'] != [''] %}
{% if config['description'] != ['TODO: write it'] %} {% if config['description'] != ['TODO: write it'] %}
:Description: {{' '.join(config['description'])}} :Description: {{' '.join(config['description'])}}
{% endif %} {% endif %}
{% endif %} {% endif %}
{% if config['type'] %} {% if config['type'] %}
:Type: {{config['type']}} :Type: {{config['type']}}
{% endif %} {% endif %}
{% if 'default' in config %}
:Default: {{config['default']}} :Default: {{config['default']}}
{% if config['version_added'] %} {% endif %}
{% if config.get('choices', False) %}
:Choices:
{% if config['choices'] is mapping %}
{% for key in config['choices'].keys() %}
- :{{key}}: {{ config['choices'][key] }}
{% endfor %}
{% else %}
{% for key in config['choices'] %}
- :{{key}}:
{% endfor %}
{% endif %}
{% endif %}
{% if config['version_added'] %}
:Version Added: {{config['version_added']}} :Version Added: {{config['version_added']}}
{% endif %} {% endif %}
{% for ini_map in config['ini']|sort(attribute='section') %} {% if config.get('ini', False) %}
:Ini Section: {{ini_map['section']}} :Ini:
:Ini Key: {{ini_map['key']}} {% for ini_map in config['ini']|sort(attribute='section') %}
{% endfor %} {% if config['ini']|length > 1 %}- {% endif %}:Section: [{{ini_map['section']}}]
{% for env_var_map in config['env']|sort(attribute='name') %} {% if config['ini']|length > 1 %} {% endif %}:Key: {{ini_map['key']}}
:Environment: :envvar:`{{env_var_map['name']}}` {% if ini_map['version_added'] %}
{% endfor %} :Version Added: {{ini_map['version_added']}}
{% if config['deprecated'] %} {% endif %}
{% if ini_map['deprecated'] %}
:Deprecated in: {{ini_map['deprecated']['version']}}
:Deprecated detail: {{ini_map['deprecated']['why']}}
{% if ini_map['deprecated']['alternatives'] %}
:Deprecated alternatives: {{ini_map['deprecated']['alternatives']}}
{% endif %}
{% endif %}
{% endfor %}
{% endif %}
{% if config.get('env', False) %}
:Environment:
{% for env_var_map in config['env']|sort(attribute='name') %}
{% if config['env']|length > 1 %}- {% endif %}:Variable: :envvar:`{{env_var_map['name']}}`
{% if env_var_map['version_added'] %}
:Version Added: {{env_var_map['version_added']}}
{% endif %}
{% if env_var_map['deprecated'] %}
:Deprecated in: {{env_var_map['deprecated']['version']}}
:Deprecated detail: {{env_var_map['deprecated']['why']}}
{% if env_var_map['deprecated']['alternatives'] %}
:Deprecated alternatives: {{env_var_map['deprecated']['alternatives']}}
{% endif %}
{% endif %}
{% endfor %}
{% endif %}
{% if config.get('vars', False) %}
:Variables:
{% for a_var in config['vars']|sort(attribute='name') %}
{% if config['vars']|length > 1 %}- {%endif%}:name: `{{a_var['name']}}`
{% if a_var['version_added'] %}
:Version Added: {{a_var['version_added']}}
{% endif %}
{% if a_var['deprecated'] %}
:Deprecated in: {{a_var['deprecated']['version']}}
:Deprecated detail: {{a_Var['deprecated']['why']}}
{% if a_var['deprecated']['alternatives'] %}
:Deprecated alternatives: {{a_var['deprecated']['alternatives']}}
{% endif %}
{% endif %}
{% endfor %}
{% endif %}
{% if config['deprecated'] %}
:Deprecated in: {{config['deprecated']['version']}} :Deprecated in: {{config['deprecated']['version']}}
:Deprecated detail: {{config['deprecated']['why']}} :Deprecated detail: {{config['deprecated']['why']}}
{% if config['deprecated']['alternatives'] %}
:Deprecated alternatives: {{config['deprecated']['alternatives']}} :Deprecated alternatives: {{config['deprecated']['alternatives']}}
{% endif %} {% endif %}
{% endif %}
{% endfor %} {% endfor %}
Environment Variables Environment Variables
===================== =====================
@ -139,20 +197,31 @@ Environment Variables
Override the default ansible config file Override the default ansible config file
{% for config_option in config_options %} {% for config_option in config_options %}
{% for env_var_map in config_options[config_option]['env'] %} {% for env_var_map in config_options[config_option]['env'] %}
.. envvar:: {{env_var_map['name']}} .. envvar:: {{env_var_map['name']}}
{% if config_options[config_option]['description'] and config_options[config_option]['description'] != [''] %} {% if config_options[config_option]['description'] and config_options[config_option]['description'] != [''] %}
{% if config_options[config_option]['description'] != ['TODO: write it'] %} {% if config_options[config_option]['description'] != ['TODO: write it'] %}
{{ ''.join(config_options[config_option]['description']) }} {{ ''.join(config_options[config_option]['description']) }}
{% endif %} {% endif %}
{% endif %} {% endif %}
See also :ref:`{{config_option}} <{{config_option}}>` See also :ref:`{{config_option}} <{{config_option}}>`
{% endfor %} {% if env_var_map['version_added'] %}
:Version Added: {{env_var_map['version_added']}}
{% endif %}
{% if env_var_map['deprecated'] %}
:Deprecated in: {{env_var_map['deprecated']['version']}}
:Deprecated detail: {{env_var_map['deprecated']['why']}}
{% if env_var_map['deprecated']['alternatives'] %}
:Deprecated alternatives: {{env_var_map['deprecated']['alternatives']}}
{% endif %}
{% endif %}
{% endfor %} {% endfor %}
{% endfor %}
{% endif %} {% endif %}

12
lib/ansible/config/base.yml
View file

@ -805,9 +805,9 @@ DEFAULT_LIBVIRT_LXC_NOSECLABEL:
env: env:
- name: LIBVIRT_LXC_NOSECLABEL - name: LIBVIRT_LXC_NOSECLABEL
deprecated: deprecated:
why: environment variables without "ANSIBLE_" prefix are deprecated why: environment variables without ``ANSIBLE_`` prefix are deprecated
version: "2.12" version: "2.12"
alternatives: the "ANSIBLE_LIBVIRT_LXC_NOSECLABEL" environment variable alternatives: the ``ANSIBLE_LIBVIRT_LXC_NOSECLABEL`` environment variable
- name: ANSIBLE_LIBVIRT_LXC_NOSECLABEL - name: ANSIBLE_LIBVIRT_LXC_NOSECLABEL
ini: ini:
- {key: libvirt_lxc_noseclabel, section: selinux} - {key: libvirt_lxc_noseclabel, section: selinux}
@ -1312,9 +1312,9 @@ DISPLAY_SKIPPED_HOSTS:
env: env:
- name: DISPLAY_SKIPPED_HOSTS - name: DISPLAY_SKIPPED_HOSTS
deprecated: deprecated:
why: environment variables without "ANSIBLE_" prefix are deprecated why: environment variables without ``ANSIBLE_`` prefix are deprecated
version: "2.12" version: "2.12"
alternatives: the "ANSIBLE_DISPLAY_SKIPPED_HOSTS" environment variable alternatives: the ``ANSIBLE_DISPLAY_SKIPPED_HOSTS`` environment variable
- name: ANSIBLE_DISPLAY_SKIPPED_HOSTS - name: ANSIBLE_DISPLAY_SKIPPED_HOSTS
ini: ini:
- {key: display_skipped_hosts, section: defaults} - {key: display_skipped_hosts, section: defaults}
@ -1665,9 +1665,9 @@ NETWORK_GROUP_MODULES:
env: env:
- name: NETWORK_GROUP_MODULES - name: NETWORK_GROUP_MODULES
deprecated: deprecated:
why: environment variables without "ANSIBLE_" prefix are deprecated why: environment variables without ``ANSIBLE_`` prefix are deprecated
version: "2.12" version: "2.12"
alternatives: the "ANSIBLE_NETWORK_GROUP_MODULES" environment variable alternatives: the ``ANSIBLE_NETWORK_GROUP_MODULES`` environment variable
- name: ANSIBLE_NETWORK_GROUP_MODULES - name: ANSIBLE_NETWORK_GROUP_MODULES
ini: ini:
- {key: network_group_modules, section: defaults} - {key: network_group_modules, section: defaults}