From fc4411adcd79ab35e7db59ad11bf31146ab387df Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Fri, 13 Nov 2020 21:31:32 +0100 Subject: [PATCH] Improve config.rst formatting (#72354) (#72487) * 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 569d937df8cfc2bd0e4c9f62b5b25021ae5e5cc1) --- docs/templates/config.rst.j2 | 133 ++++++++++++++++++++++++++--------- lib/ansible/config/base.yml | 12 ++-- 2 files changed, 107 insertions(+), 38 deletions(-) diff --git a/docs/templates/config.rst.j2 b/docs/templates/config.rst.j2 index 44be320d4e3..35a540170fd 100644 --- a/docs/templates/config.rst.j2 +++ b/docs/templates/config.rst.j2 @@ -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 %} diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml index 253a04ba9c7..17f64a625f9 100644 --- a/lib/ansible/config/base.yml +++ b/lib/ansible/config/base.yml @@ -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}