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

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

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