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