diff --git a/changelogs/fragments/34-version_added.yml b/changelogs/fragments/34-version_added.yml new file mode 100644 index 00000000..223d7d05 --- /dev/null +++ b/changelogs/fragments/34-version_added.yml @@ -0,0 +1,4 @@ +bugfixes: + - "Fix escaping of collection names in version added statements, and fix collection names for roles options (https://github.com/ansible-community/antsibull-docs/pull/34)." +minor_changes: + - "Replace ``ansible.builtin`` with ``ansible-core``, ``ansible-base``, or ``Ansible`` in version added collection names. Also write `` `` instead of `` of `` (https://github.com/ansible-community/antsibull-docs/pull/34)." diff --git a/src/antsibull_docs/data/docsite/macros/attributes.rst.j2 b/src/antsibull_docs/data/docsite/macros/attributes.rst.j2 index 6f48e38b..6875c037 100644 --- a/src/antsibull_docs/data/docsite/macros/attributes.rst.j2 +++ b/src/antsibull_docs/data/docsite/macros/attributes.rst.j2 @@ -4,6 +4,8 @@ SPDX-License-Identifier: GPL-3.0-or-later #} +{% from 'macros/version_added.rst.j2' import version_added_rst %} + {% macro in_rst(attributes) %} .. rst-class:: ansible-option-table @@ -70,9 +72,9 @@ {%- endif %} {% endif %} -{% if data['version_added'] is still_relevant(collection=data['version_added_collection']) %} +{% if data['version_added'] is still_relevant(collection=data['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{data['version_added']}@ of @{ data['version_added_collection'] | rst_escape }@` + :ansible-option-versionadded:`added in @{ version_added_rst(data['version_added'], data['version_added_collection'] or collection) }@` {% endif %} {% for desc in data['details'] %} diff --git a/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 b/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 index c25dfe56..67875565 100644 --- a/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 +++ b/src/antsibull_docs/data/docsite/macros/parameters.rst.j2 @@ -6,6 +6,7 @@ {% from 'macros/deprecates.rst.j2' import in_rst as deprecates_rst with context %} {% from 'macros/deprecates.rst.j2' import in_html as deprecates_html with context %} +{% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %} {% macro in_rst(elements, suboption_key='suboptions', parameter_html_prefix='', parameter_rst_prefix='') %} .. rst-class:: ansible-option-table @@ -50,10 +51,10 @@ :ansible-option-type:`@{ value['type'] | documented_type }@` {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif -%} {%- if value['required'] %} / :ansible-option-required:`required`{% endif %} -{%- if value['version_added'] is still_relevant(collection=value['version_added_collection']) %} +{%- if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{value['version_added']}@ of @{ value['version_added_collection'] | escape }@` + :ansible-option-versionadded:`added in @{ version_added_rst(value['version_added'], value['version_added_collection'] or collection) }@` {% endif %} {%- if plugin_type != 'module' %} @@ -129,41 +130,41 @@ [@{ ini['section'] }@] @{ ini['key'] }@ = @{ value['default'] | default('VALUE') }@ -{% if ini['version_added'] is still_relevant(collection=ini['version_added_collection']) %} - :ansible-option-versionadded:`added in @{ini['version_added']}@ of @{ ini['version_added_collection'] | rst_ify }@` +{% if ini['version_added'] is still_relevant(collection=ini['version_added_collection'] or collection) %} + :ansible-option-versionadded:`added in @{ version_added_rst(ini['version_added'], ini['version_added_collection'] or collection) }@` {% endif %} @{ deprecates_rst(ini['deprecated'], collection, 8) }@ {% endfor %} {% endif %} {% for env in value['env'] %} - Environment variable: @{ env['name'] | rst_escape }@ -{% if env['version_added'] is still_relevant(collection=env['version_added_collection']) %} +{% if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{env['version_added']}@ of @{ env['version_added_collection'] | rst_ify }@` + :ansible-option-versionadded:`added in @{ version_added_rst(env['version_added'], env['version_added_collection'] or collection) }@` {% endif %} @{ deprecates_rst(env['deprecated'], collection, 8) }@ {% endfor %} {% for myvar in value['vars'] %} - Variable: @{ myvar['name'] | rst_escape }@ -{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection']) %} +{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{myvar['version_added']}@ of @{ myvar['version_added_collection'] | rst_ify }@` + :ansible-option-versionadded:`added in @{ version_added_rst(myvar['version_added'], myvar['version_added_collection'] or collection) }@` {% endif %} @{ deprecates_rst(myvar['deprecated'], collection, 8) }@ {% endfor %} {% for kw in value['keyword'] %} - Keyword: @{ kw['name'] | rst_escape }@ -{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %} +{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | rst_ify }@` + :ansible-option-versionadded:`added in @{ version_added_rst(kw['version_added'], kw['version_added_collection'] or collection) }@` {% endif %} @{ deprecates_rst(kw['deprecated'], collection, 8) }@ {% endfor %} {% for mycli in value['cli'] %} - CLI argument: @{ mycli['option'] | rst_escape }@ -{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection']) %} +{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{mycli['version_added']}@ of @{ mycli['version_added_collection'] | rst_ify }@` + :ansible-option-versionadded:`added in @{ version_added_rst(mycli['version_added'], mycli['version_added_collection'] or collection) }@` {% endif %} @{ deprecates_rst(mycli['deprecated'], collection, 8) }@ {% endfor %} @@ -213,8 +214,8 @@ / required {% endif %}

-{% if value['version_added'] is still_relevant(collection=value['version_added_collection']) %} -

added in @{value['version_added']}@ of @{ value['version_added_collection'] | escape }@

+{% if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %} +

added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@

{% endif %} {% if plugin_type != 'module' %} @{ deprecates_html(value['deprecated'], collection) }@ @@ -268,8 +269,8 @@ {% for ini in value['ini'] %}
[@{ ini['section'] | escape }@]
   @{ ini['key'] | escape }@ = @{ value['default'] | default('VALUE') | escape }@
-{% if ini['version_added'] is still_relevant(collection=ini['version_added_collection']) %} -

added in @{ini['version_added']}@ of @{ ini['version_added_collection'] | html_ify }@

+{% if ini['version_added'] is still_relevant(collection=ini['version_added_collection'] or collection) %} +

added in @{ version_added_html(ini['version_added'], ini['version_added_collection'] or collection) }@

{% endif %} @{ deprecates_html(ini['deprecated'], collection) }@ {% endfor %} @@ -278,8 +279,8 @@ {% for env in value['env'] %}
  • Environment variable: @{ env['name'] | escape }@

    -{% if env['version_added'] is still_relevant(collection=env['version_added_collection']) %} -

    added in @{env['version_added']}@ of @{ env['version_added_collection'] | html_ify }@

    +{% if env['version_added'] is still_relevant(collection=env['version_added_collection'] or collection) %} +

    added in @{ version_added_html(env['version_added'], env['version_added_collection'] or collection) }@

    {% endif %} @{ deprecates_html(env['deprecated'], collection) }@
  • @@ -287,8 +288,8 @@ {% for myvar in value['vars'] %}
  • Variable: @{ myvar['name'] | escape }@

    -{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection']) %} -

    added in @{myvar['version_added']}@ of @{ myvar['version_added_collection'] | html_ify }@

    +{% if myvar['version_added'] is still_relevant(collection=myvar['version_added_collection'] or collection) %} +

    added in @{ version_added_html(myvar['version_added'], myvar['version_added_collection'] or collection) }@

    {% endif %} @{ deprecates_html(myvar['deprecated'], collection) }@
  • @@ -296,8 +297,8 @@ {% for kw in value['keyword'] %}
  • Keyword: @{ kw['name'] | escape }@

    -{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection']) %} -

    added in @{kw['version_added']}@ of @{ kw['version_added_collection'] | html_ify }@

    +{% if kw['version_added'] is still_relevant(collection=kw['version_added_collection'] or collection) %} +

    added in @{ version_added_html(kw['version_added'], kw['version_added_collection'] or collection) }@

    {% endif %} @{ deprecates_html(kw['deprecated'], collection) }@
  • @@ -305,8 +306,8 @@ {% for mycli in value['cli'] %}
  • CLI argument: @{ mycli['option'] | escape }@

    -{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection']) %} -

    added in @{mycli['version_added']}@ of @{ mycli['version_added_collection'] | html_ify }@

    +{% if mycli['version_added'] is still_relevant(collection=mycli['version_added_collection'] or collection) %} +

    added in @{ version_added_html(mycli['version_added'], mycli['version_added_collection'] or collection) }@

    {% endif %} @{ deprecates_html(mycli['deprecated'], collection) }@
  • diff --git a/src/antsibull_docs/data/docsite/macros/returnvalues.rst.j2 b/src/antsibull_docs/data/docsite/macros/returnvalues.rst.j2 index d15d2b89..eac46cdb 100644 --- a/src/antsibull_docs/data/docsite/macros/returnvalues.rst.j2 +++ b/src/antsibull_docs/data/docsite/macros/returnvalues.rst.j2 @@ -4,6 +4,8 @@ SPDX-License-Identifier: GPL-3.0-or-later #} +{% from 'macros/version_added.rst.j2' import version_added_rst, version_added_html %} + {% macro in_rst(elements) %} .. rst-class:: ansible-option-table @@ -40,10 +42,10 @@ :ansible-option-type:`@{ value['type'] | documented_type }@` {%- if value['type'] == 'list' and value['elements'] is not none %} / :ansible-option-elements:`elements=@{ value['elements'] | documented_type }@`{% endif %} -{%- if value['version_added'] is still_relevant(collection=value['version_added_collection']) %} +{%- if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %} - :ansible-option-versionadded:`added in @{value['version_added']}@ of @{ value['version_added_collection'] | rst_escape }@` + :ansible-option-versionadded:`added in @{ version_added_rst(value['version_added'], value['version_added_collection'] or collection) }@` {% endif %} {# description #} @@ -135,8 +137,8 @@ / elements=@{ value['elements'] | documented_type }@ {% endif %}

    -{% if value['version_added'] is still_relevant(collection=value['version_added_collection']) %} -

    added in @{value['version_added']}@ of @{ value['version_added_collection'] | escape }@

    +{% if value['version_added'] is still_relevant(collection=value['version_added_collection'] or collection) %} +

    added in @{ version_added_html(value['version_added'], value['version_added_collection'] or collection) }@

    {% endif %} {# description #} diff --git a/src/antsibull_docs/data/docsite/macros/version_added.rst.j2 b/src/antsibull_docs/data/docsite/macros/version_added.rst.j2 new file mode 100644 index 00000000..139e64cd --- /dev/null +++ b/src/antsibull_docs/data/docsite/macros/version_added.rst.j2 @@ -0,0 +1,37 @@ +{# + Copyright (c) Ansible Project + GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt) + SPDX-License-Identifier: GPL-3.0-or-later +#} + +{% macro ansible_name(version) -%} +{%- if version.startswith('2.10.') -%} +ansible-base +{%- elif version.startswith('1.') or (version.startswith('2.') and (version | length == 3 or version[3] == '.')) -%} +Ansible +{%- elif version.startswith('2.10.') or version == '2.10' -%} +ansible-base +{%- else -%} +ansible-core +{%- endif -%} +{%- endmacro %} + +{% macro version_added_rst(version_added, version_added_collection=None) -%} +{%- if version_added_collection == 'ansible.builtin' -%} +@{ ansible_name(version_added) }@ @{ version_added | rst_escape }@ +{%- elif version_added_collection -%} +@{ version_added_collection | rst_escape }@ @{ version_added | rst_escape }@ +{%- else -%} +@{ version_added | rst_escape }@ +{%- endif -%} +{%- endmacro %} + +{% macro version_added_html(version_added, version_added_collection=None) -%} +{%- if version_added_collection == 'ansible.builtin' -%} +@{ ansible_name(version_added) }@ @{ version_added | escape }@ +{%- elif version_added_collection -%} +@{ version_added_collection | escape }@ @{ version_added | escape }@ +{%- else -%} +@{ version_added | escape }@ +{%- endif -%} +{%- endmacro %} diff --git a/src/antsibull_docs/data/docsite/plugin.rst.j2 b/src/antsibull_docs/data/docsite/plugin.rst.j2 index df4a72e9..61efc204 100644 --- a/src/antsibull_docs/data/docsite/plugin.rst.j2 +++ b/src/antsibull_docs/data/docsite/plugin.rst.j2 @@ -9,6 +9,7 @@ {% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %} {% from 'macros/returnvalues.rst.j2' import in_rst as return_docs_rst with context %} {% from 'macros/returnvalues.rst.j2' import in_html as return_docs_html with context %} +{% from 'macros/version_added.rst.j2' import version_added_rst %} .. Document meta :orphan: @@ -110,8 +111,8 @@ .. version_added -{% if doc['version_added'] is still_relevant(collection=doc['version_added_collection']) -%} -.. versionadded:: @{ doc['version_added'] }@ of @{ doc['version_added_collection'] | rst_ify }@ +{% if doc['version_added'] is still_relevant(collection=doc['version_added_collection'] or collection) -%} +.. versionadded:: @{ version_added_rst(doc['version_added'], doc['version_added_collection'] or collection) }@ {% endif %} .. contents:: diff --git a/src/antsibull_docs/data/docsite/role.rst.j2 b/src/antsibull_docs/data/docsite/role.rst.j2 index e308f7de..ca2e6107 100644 --- a/src/antsibull_docs/data/docsite/role.rst.j2 +++ b/src/antsibull_docs/data/docsite/role.rst.j2 @@ -6,6 +6,7 @@ {% from 'macros/parameters.rst.j2' import in_rst as parameters_rst with context %} {% from 'macros/parameters.rst.j2' import in_html as parameters_html with context %} +{% from 'macros/version_added.rst.j2' import version_added_rst %} .. Document meta :orphan: @@ -91,7 +92,7 @@ .. version_added {% if ep_doc['version_added'] is still_relevant(collection=collection) -%} -.. versionadded:: @{ ep_doc['version_added'] }@ of @{ collection | rst_ify }@ +.. versionadded:: @{ version_added_rst(ep_doc['version_added'], collection) }@ {% endif %} .. Deprecated