Add version into generated files

changelogs/fragments/205-version.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "Insert the antsibull-docs version as a comment or metadata into the generated files (https://github.com/ansible-community/antsibull-docs/pull/205)."

src/antsibull_docs/cli/antsibull_docs.py

@@ -35,6 +35,7 @@
 from ..constants import DOCUMENTABLE_PLUGINS  # noqa: E402
 from ..docs_parsing.fqcn import is_fqcn  # noqa: E402
 from ..schemas.app_context import DocsAppContext  # noqa: E402
+from ..test_helpers import ci_setup  # noqa: E402
 from .doc_commands import (  # noqa: E402
     collection,
     collection_plugins,
@@ -794,6 +795,7 @@ def main() -> int:
         :2: There was a problem with the command line arguments
         :3: Unexpected problem downloading ansible-core
     """
+    ci_setup()
     return run(sys.argv)
 
 

src/antsibull_docs/cli/doc_commands/sphinx_init.py

@@ -13,6 +13,8 @@
 
 from antsibull_core.logging import log
 
+import antsibull_docs
+
 from ... import app_context
 from ...jinja2.environment import doc_environment
 
@@ -176,6 +178,7 @@ def site_init() -> int:
                 extra_html_context=extra_html_context,
                 extra_html_theme_options=extra_html_theme_options,
                 output_format=output_format,
+                antsibull_docs_version=antsibull_docs.__version__,
             )
             + "\n"
         )

src/antsibull_docs/data/docsite/ansible-docsite/list_of_callback_plugins.rst.j2

@@ -6,6 +6,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. _list_of_@{ callback_type }@_callback_plugins:
 
 Index of all @{ callback_type | capitalize }@ Callback Plugins

src/antsibull_docs/data/docsite/ansible-docsite/list_of_collections.rst.j2

@@ -6,6 +6,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. _list_of_collections:
 
 Collection Index

src/antsibull_docs/data/docsite/ansible-docsite/list_of_collections_by_namespace.rst.j2

@@ -8,6 +8,9 @@
 :orphan:
 {% endif %}
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. _list_of_collections_@{ namespace }@:
 
 {% set title = 'Collections in the ' ~ (namespace | title) ~ ' Namespace' | rst_ify -%}

src/antsibull_docs/data/docsite/ansible-docsite/list_of_env_variables.rst.j2

@@ -6,6 +6,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. _list_of_collection_env_vars:
 
 Index of all Collection Environment Variables

src/antsibull_docs/data/docsite/ansible-docsite/list_of_plugins.rst.j2

@@ -6,6 +6,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. _list_of_@{ plugin_type }@_plugins:
 
 {% if plugin_type == 'module' %}

src/antsibull_docs/data/docsite/ansible-docsite/plugin-deprecation.rst.j2

@@ -9,6 +9,9 @@
 {# avoids rST "isn't included in any toctree" errors for module docs #}
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. _@{ module }@_@{ plugin_type }@_alias_@{ alias }@:
 
 {% if short_description %}

src/antsibull_docs/data/docsite/ansible-docsite/plugin-error.rst.j2

@@ -11,6 +11,9 @@
 :github_url: @{ edit_on_github_url }@?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite_pr
 {% endif %}
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. Document body
 
 .. Anchors

src/antsibull_docs/data/docsite/ansible-docsite/plugin-redirect.rst.j2

@@ -8,6 +8,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. Anchors
 
 .. _ansible_collections.@{plugin_name}@_@{plugin_type}@:

src/antsibull_docs/data/docsite/ansible-docsite/plugin-tombstone.rst.j2

@@ -8,6 +8,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 .. Anchors
 
 .. _ansible_collections.@{plugin_name}@_@{plugin_type}@:

src/antsibull_docs/data/docsite/ansible-docsite/plugin.rst.j2

@@ -25,11 +25,8 @@
 .. |antsibull-internal-nbsp| unicode:: 0xA0
     :trim:
 
-{# If we can put together source and github repo, we could make the Edit me of github button work.
-   See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html
-   for more information
-:source: @{ source }@
--#}
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
 
 .. Anchors
 

src/antsibull_docs/data/docsite/ansible-docsite/plugins_by_collection.rst.j2

@@ -10,6 +10,9 @@
 :orphan:
 {% endif %}
 
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
+
 {% macro list_plugins(plugin_type) %}
 {%   for name, desc in plugin_maps[plugin_type].items() | sort %}
 * :ansplugin:`@{ name }@ @{ plugin_type }@ <@{ collection_name }@.@{ name }@#@{ plugin_type }@>` -- @{ desc | rst_ify(plugin_fqcn=collection_name ~ '.' ~ name, plugin_type=plugin_type) | indent(width=2) }@

src/antsibull_docs/data/docsite/ansible-docsite/role.rst.j2

@@ -20,11 +20,8 @@
 .. |antsibull-internal-nbsp| unicode:: 0xA0
     :trim:
 
-{# If we can put together source and github repo, we could make the Edit me of github button work.
-   See meta.get("source") in Ansible's docs/docsite/_themes/sphinx_rtd_theme/breadcrumbs.html
-   for more information
-:source: @{ source }@
--#}
+.. meta::
+  :antsibull-docs: @{ antsibull_docs_version }@
 
 .. Anchors
 

src/antsibull_docs/data/docsite/simplified-rst/list_of_callback_plugins.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 Index of all @{ callback_type | capitalize }@ Callback Plugins
 =============@{ '=' * (callback_type | length) }@=================
 

src/antsibull_docs/data/docsite/simplified-rst/list_of_collections.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 Collection Index
 ================
 

src/antsibull_docs/data/docsite/simplified-rst/list_of_collections_by_namespace.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% if not breadcrumbs %}
 :orphan:
 {% endif %}

src/antsibull_docs/data/docsite/simplified-rst/list_of_plugins.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% if plugin_type == 'module' %}
 Index of all Modules
 ====================

src/antsibull_docs/data/docsite/simplified-rst/plugin-deprecation.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% if short_description %}
 {%   set title = alias ~ ' ' ~ plugin_type ~ ' -- ' ~ short_description | rst_ify %}
 {% else %}

src/antsibull_docs/data/docsite/simplified-rst/plugin-error.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% set title = plugin_name ~ ' ' ~ plugin_type -%}
 
 @{ title }@

src/antsibull_docs/data/docsite/simplified-rst/plugin-redirect.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% set title = plugin_name ~ ' ' ~ plugin_type -%}
 
 @{ title }@

src/antsibull_docs/data/docsite/simplified-rst/plugin-tombstone.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 @{ plugin_name }@
 @{ '+' * plugin_name|length }@
 

src/antsibull_docs/data/docsite/simplified-rst/plugin.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% from 'macros/attributes.rst.j2' import in_rst as attributes_rst with context -%}
 {% from 'macros/collection_links.rst.j2' import add as add_collection_links with context -%}
 {% from 'macros/parameters.rst.j2' import in_html as parameters_html with context -%}

src/antsibull_docs/data/docsite/simplified-rst/plugins_by_collection.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% from 'macros/collection_links.rst.j2' import add as add_collection_links with context -%}
 
 {% macro list_plugins(plugin_type) %}

src/antsibull_docs/data/docsite/simplified-rst/role.rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 {% from 'macros/attributes.rst.j2' import in_rst as attributes_rst with context -%}
 {% from 'macros/collection_links.rst.j2' import add as add_collection_links with context -%}
 {% from 'macros/parameters.rst.j2' import in_html as parameters_html with context -%}

src/antsibull_docs/data/sphinx_init/_gitignore.j2

@@ -2,5 +2,7 @@
 # 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
 
+# Created with antsibull-docs @{ antsibull_docs_version }@
+
 /temp-rst
 /build

src/antsibull_docs/data/sphinx_init/antsibull-docs_cfg.j2

@@ -2,6 +2,8 @@
 # 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
 
+# Created with antsibull-docs @{ antsibull_docs_version }@
+
 breadcrumbs = @{ breadcrumbs | tojson }@
 indexes = @{ indexes | tojson }@
 use_html_blobs = @{ use_html_blobs | tojson }@

src/antsibull_docs/data/sphinx_init/build_sh.j2

@@ -3,6 +3,8 @@
 # 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
 
+# Created with antsibull-docs @{ antsibull_docs_version }@
+
 set -e
 
 pushd "$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"

src/antsibull_docs/data/sphinx_init/conf_py.j2

@@ -2,6 +2,8 @@
 # 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
 
+# Created with antsibull-docs @{ antsibull_docs_version }@
+
 # This file only contains a selection of the most common options. For a full list see the
 # documentation:
 # http://www.sphinx-doc.org/en/master/config

src/antsibull_docs/data/sphinx_init/requirements_txt.j2

@@ -2,6 +2,8 @@
 # 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
 
+# Created with antsibull-docs @{ antsibull_docs_version }@
+
 antsibull-docs >= 2.0.0, < 3.0.0
 ansible-pygments
 sphinx

src/antsibull_docs/data/sphinx_init/rst_index_rst.j2

@@ -4,6 +4,8 @@
   SPDX-License-Identifier: GPL-3.0-or-later
 #}
 
+.. Created with antsibull-docs @{ antsibull_docs_version }@
+
 .. _docsite_root_index:
 
 Welcome to my Ansible collection documentation

src/antsibull_docs/test_helpers.py

@@ -0,0 +1,39 @@
+# Author: Felix Fontein <felix@fontein.de>
+# 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
+# SPDX-FileCopyrightText: 2023, Ansible Project
+"""Detect and setup for CI tests"""
+
+from __future__ import annotations
+
+import os
+
+import antsibull_docs
+
+# Use an environment variable with a special value as a CI marker
+ANTSIBULL_DOCS_CI_ENV_MARKER_NAME = "_ANTSIBULL_DOCS_CI_MARKER"
+ANTSIBULL_DOCS_CI_ENV_MARKER_VALUE = "Noo4oogongae"
+
+# The version string to use when in CI
+ANTSIBULL_DOCS_CI_VERSION = "<ANTSIBULL_DOCS_VERSION>"
+
+
+def is_in_antsibull_ci():
+    """
+    Determine whether the code is running in CI.
+    """
+    return (
+        os.environ.get(ANTSIBULL_DOCS_CI_ENV_MARKER_NAME)
+        == ANTSIBULL_DOCS_CI_ENV_MARKER_VALUE
+    )
+
+
+def ci_setup():
+    """
+    Changes some behavior, such as the version, when running in CI.
+    """
+    if not is_in_antsibull_ci():
+        return
+
+    antsibull_docs.__version__ = ANTSIBULL_DOCS_CI_VERSION

src/antsibull_docs/write_docs/__init__.py

@@ -12,6 +12,8 @@
 from antsibull_core.logging import log
 from jinja2 import Template
 
+import antsibull_docs
+
 mlog = log.fields(mod=__name__)
 
 #: Mapping of plugins to nonfatal errors.  This is the type to use when accepting the plugin.
@@ -29,6 +31,8 @@
 
 def _render_template(_template: Template, _name: str, **kwargs) -> str:
     try:
-        return _template.render(**kwargs)
+        return _template.render(
+            antsibull_docs_version=antsibull_docs.__version__, **kwargs
+        )
     except Exception as exc:
         raise RuntimeError(f"Error while rendering {_name}") from exc

tests/functional/baseline-default/collections/callback_index_stdout.rst

@@ -1,6 +1,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
 .. _list_of_stdout_callback_plugins:
 
 Index of all Stdout Callback Plugins

tests/functional/baseline-default/collections/environment_variables.rst

@@ -1,6 +1,9 @@
 
 :orphan:
 
+.. meta::
+  :antsibull-docs: <ANTSIBULL_DOCS_VERSION>
+
 .. _list_of_collection_env_vars:
 
 Index of all Collection Environment Variables