Adds option to disable TOC

changelogs/fragments/190-add-toc.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - Add a new configuration option ``add_toc`` to the changelog configuration file.
+    If set to ``false`` (default is ``true``), a table of contents is not added to the top of the changelog.
+    (https://github.com/ansible-community/antsibull-changelog/pull/191)

docs/changelog-configuration.md

@@ -18,6 +18,11 @@ new configurations.
 
 If set to `false`, the plugin short description is used. If set to `true`, a period is added to the end of the plugin short description if no other end punctuation is present. Setting to `true` complies with the [Ansible changelog format](https://docs.ansible.com/ansible/latest/community/development_process.html#changelogs-how-to-format).
 
+### `add_toc` (boolean)
+
+The default value is `true`.
+
+If set to `true`, a table of contents is added to the top of the changelog.
 
 ### `always_refresh` (string)
 

src/antsibull_changelog/changelog_generator.py

@@ -382,15 +382,16 @@ def generate_to(  # pylint: disable=too-many-arguments
             if only_latest:
                 break
 
-    def generate(self, only_latest: bool = False) -> str:
+    def generate(self, only_latest: bool = False, add_toc: bool = True) -> str:
         """
         Generate the changelog as reStructuredText.
         """
         builder = RstBuilder()
 
         if not only_latest:
             builder.set_title(self.get_title())
-            builder.add_raw_rst(".. contents:: Topics\n")
+            if add_toc:
+                builder.add_raw_rst(".. contents:: Topics\n")
 
             if self.changes.ancestor and self.config.mention_ancestor:
                 builder.add_raw_rst(
@@ -600,7 +601,7 @@ def generate_changelog(  # pylint: disable=too-many-arguments
         changelog_path = os.path.join(paths.changelog_dir, changelog_filename)
 
     generator = ChangelogGenerator(config, changes, flatmap=flatmap)
-    rst = generator.generate(only_latest=only_latest)
+    rst = generator.generate(only_latest=only_latest, add_toc=config.add_toc)
 
     with open(changelog_path, "wb") as changelog_fd:
         changelog_fd.write(rst.encode("utf-8"))

src/antsibull_changelog/changes.py

@@ -39,7 +39,7 @@ def _sort_dict_by_key(dictionary: Mapping[str, Any]) -> dict[str, Any]:
 
 
 def _sort_modules_plugins_objects(
-    object_list: Sequence[Mapping[str, Any]]
+    object_list: Sequence[Mapping[str, Any]],
 ) -> list[dict[str, Any]]:
     return sorted(
         (_sort_dict_by_key(obj) for obj in object_list), key=lambda obj: obj["name"]

src/antsibull_changelog/config.py

@@ -389,6 +389,7 @@ class ChangelogConfig:
         "alphanumerical",
     ]
     vcs: Literal["none", "auto", "git"]
+    add_toc: bool
 
     def __init__(
         self,
@@ -480,6 +481,8 @@ def __init__(
 
         self.vcs = self.config.get("vcs", "none")
 
+        self.add_toc = self.config.get("add_toc", True)
+
         self._validate_config(ignore_is_other_project)
 
     def _validate_config(self, ignore_is_other_project: bool) -> None:
@@ -537,6 +540,7 @@ def store(self) -> None:  # noqa: C901
             "changelog_nice_yaml": self.changelog_nice_yaml,
             "changelog_sort": self.changelog_sort,
             "vcs": self.vcs,
+            "add_toc": self.add_toc,
         }
         if not self.is_collection:
             if self.use_semantic_versioning:
@@ -618,6 +622,7 @@ def default(
             "changelog_nice_yaml": False,
             "changelog_sort": "alphanumerical",
             "vcs": "auto",
+            "add_toc": True,
         }
         if title is not None:
             config["title"] = title

src/antsibull_changelog/rendering/changelog.py

@@ -144,13 +144,19 @@ def generate_to(  # pylint: disable=too-many-arguments
             if only_latest:
                 break
 
-    def generate(self, renderer: DocumentRenderer, only_latest: bool = False) -> None:
+    def generate(
+        self,
+        renderer: DocumentRenderer,
+        only_latest: bool = False,
+        add_toc: bool = True,
+    ) -> None:
         """
         Generate the changelog.
         """
         if not only_latest:
             renderer.set_title(self.get_title())
-            renderer.add_toc("Topics")
+            if add_toc:
+                renderer.add_toc("Topics")
 
             if self.changes.ancestor and self.config.mention_ancestor:
                 renderer.add_text(
@@ -413,7 +419,7 @@ def generate_changelog(  # pylint: disable=too-many-arguments
     renderer = create_document_renderer(
         document_format, start_level=1 if only_latest else 0
     )
-    generator.generate(renderer, only_latest=only_latest)
+    generator.generate(renderer, only_latest=only_latest, add_toc=config.add_toc)
 
     text = renderer.render()
     for warning in renderer.get_warnings():