Improve config.rst formatting (#72354)
* 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.
This commit is contained in:
Felix Fontein
GitHub
parent
7f86e0715c
commit
569d937df8
2 changed files with 107 additions and 38 deletions
133
docs/templates/config.rst.j2
vendored
133
docs/templates/config.rst.j2
vendored
|
|
@ -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 %}
|
||||
|
|
|
|||
|
|
@ -852,9 +852,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}
|
||||
|
|
@ -1342,9 +1342,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}
|
||||
|
|
@ -1695,9 +1695,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}
|
||||
|
|
|
|||
Loading…
Reference in a new issue