diff --git a/changelogs/fragments/190-add-toc.yml b/changelogs/fragments/190-add-toc.yml new file mode 100644 index 00000000..b452a2e7 --- /dev/null +++ b/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) diff --git a/docs/changelog-configuration.md b/docs/changelog-configuration.md index e6514afc..a8e24fee 100644 --- a/docs/changelog-configuration.md +++ b/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) diff --git a/src/antsibull_changelog/changelog_generator.py b/src/antsibull_changelog/changelog_generator.py index 6a3af4c9..c97ff1b7 100644 --- a/src/antsibull_changelog/changelog_generator.py +++ b/src/antsibull_changelog/changelog_generator.py @@ -382,7 +382,7 @@ 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. """ @@ -390,7 +390,8 @@ def generate(self, only_latest: bool = False) -> str: 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")) diff --git a/src/antsibull_changelog/changes.py b/src/antsibull_changelog/changes.py index a0e87ed3..47ad569b 100644 --- a/src/antsibull_changelog/changes.py +++ b/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"] diff --git a/src/antsibull_changelog/config.py b/src/antsibull_changelog/config.py index 1c36dfc5..93d99bdb 100644 --- a/src/antsibull_changelog/config.py +++ b/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 diff --git a/src/antsibull_changelog/rendering/changelog.py b/src/antsibull_changelog/rendering/changelog.py index 86e1a1aa..cbdfbda4 100644 --- a/src/antsibull_changelog/rendering/changelog.py +++ b/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():