diff --git a/changelogs/config.yaml b/changelogs/config.yaml index eebf2d40..391d6d26 100644 --- a/changelogs/config.yaml +++ b/changelogs/config.yaml @@ -36,3 +36,4 @@ title: Ansible Changelog Tool output_formats: - rst - md +add_plugin_period: false diff --git a/changelogs/fragments/162-add-plugin-period.yaml b/changelogs/fragments/162-add-plugin-period.yaml new file mode 100644 index 00000000..7453397f --- /dev/null +++ b/changelogs/fragments/162-add-plugin-period.yaml @@ -0,0 +1,2 @@ +minor_changes: + - "Adds period where needed at end of new plugin short descriptions. Controlled by the ``add_plugin_period`` option in the config file (https://github.com/ansible-community/antsibull-changelog/issues/87)." \ No newline at end of file diff --git a/docs/changelog-configuration.md b/docs/changelog-configuration.md index ab4cb39b..5e0b6324 100644 --- a/docs/changelog-configuration.md +++ b/docs/changelog-configuration.md @@ -11,6 +11,14 @@ This document describes all settings that are supported in ## General options +### `add_plugin_period` (boolean) + +The default value is `false` for existing configurations, and `true` for +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). + + ### `always_refresh` (string) Allowed values are `none`, `full`, or a comma-separated combination of diff --git a/src/antsibull_changelog/cli.py b/src/antsibull_changelog/cli.py index 64e8cf31..a3ab6c31 100644 --- a/src/antsibull_changelog/cli.py +++ b/src/antsibull_changelog/cli.py @@ -471,6 +471,7 @@ def _do_refresh( # pylint: disable=too-many-arguments version=changes.latest_version, force_reload=args.reload_plugins, use_ansible_doc=args.use_ansible_doc, + add_plugin_period=config.add_plugin_period, ) allow_removals = refresh_plugins == "allow-removal" @@ -665,6 +666,7 @@ def command_release(args: Any) -> int: version=version, force_reload=args.reload_plugins, use_ansible_doc=args.use_ansible_doc, + add_plugin_period=config.add_plugin_period, ) fragments = load_fragments(paths, config) lint_rc = lint_fragments(config, fragments, []) @@ -749,6 +751,7 @@ def command_generate(args: Any) -> int: # pylint: disable=too-many-locals collection_details=collection_details, version=changes.latest_version, force_reload=args.reload_plugins, + add_plugin_period=config.add_plugin_period, ) if output and len(config.output_formats) > 1 and not output_format: print( diff --git a/src/antsibull_changelog/config.py b/src/antsibull_changelog/config.py index a42cd18c..81908c63 100644 --- a/src/antsibull_changelog/config.py +++ b/src/antsibull_changelog/config.py @@ -378,6 +378,7 @@ class ChangelogConfig: is_other_project: bool sections: Mapping[str, str] output_formats: set[TextFormat] + add_plugin_period: bool def __init__( self, @@ -465,6 +466,8 @@ def __init__( f"Found unknown extension in output_formats: {exc}" ) from exc + self.add_plugin_period = self.config.get("add_plugin_period", False) + self._validate_config(ignore_is_other_project) def _validate_config(self, ignore_is_other_project: bool) -> None: @@ -514,6 +517,7 @@ def store(self) -> None: # noqa: C901 "trivial_section_name": self.trivial_section_name, "ignore_other_fragment_extensions": self.ignore_other_fragment_extensions, "sanitize_changelog": self.sanitize_changelog, + "add_plugin_period": self.add_plugin_period, } if not self.is_collection: if self.use_semantic_versioning: @@ -592,6 +596,7 @@ def default( "use_fqcn": True, "ignore_other_fragment_extensions": True, "sanitize_changelog": True, + "add_plugin_period": True, } if title is not None: config["title"] = title diff --git a/src/antsibull_changelog/plugins.py b/src/antsibull_changelog/plugins.py index 2b261a82..2746d082 100644 --- a/src/antsibull_changelog/plugins.py +++ b/src/antsibull_changelog/plugins.py @@ -67,7 +67,9 @@ def __init__( @staticmethod def from_dict( - data: dict[str, dict[str, dict[str, Any]]], category: str = "plugin" + data: dict[str, dict[str, dict[str, Any]]], + category: str = "plugin", + add_plugin_period: bool = False, ) -> list[PluginDescription]: """ Return a list of ``PluginDescription`` objects from the given data. @@ -79,12 +81,19 @@ def from_dict( for plugin_type, plugin_data in data.items(): for plugin_name, plugin_details in plugin_data.items(): + description = plugin_details["description"] + if ( + add_plugin_period + and description + and not description.endswith((".", ",", "!", "?")) + ): + description += "." plugins.append( PluginDescription( plugin_type=plugin_type, name=plugin_name, namespace=plugin_details.get("namespace"), - description=plugin_details["description"], + description=description, version_added=plugin_details["version_added"], category=category, ) @@ -543,12 +552,13 @@ def _refresh_plugin_cache( return plugins_data -def load_plugins( +def load_plugins( # pylint: disable=too-many-arguments paths: PathsConfig, collection_details: CollectionDetails, version: str, force_reload: bool = False, use_ansible_doc: bool = False, + add_plugin_period: bool = False, ) -> list[PluginDescription]: """ Load plugins from ansible-doc. @@ -582,10 +592,17 @@ def load_plugins( ) store_yaml(plugin_cache_path, plugins_data) - plugins = PluginDescription.from_dict(plugins_data["plugins"]) + plugins = PluginDescription.from_dict( + plugins_data["plugins"], + add_plugin_period=add_plugin_period, + ) if "objects" in plugins_data: plugins.extend( - PluginDescription.from_dict(plugins_data["objects"], category="object") + PluginDescription.from_dict( + plugins_data["objects"], + category="object", + add_plugin_period=add_plugin_period, + ) ) return plugins diff --git a/tests/functional/test_changelog_basic_ansible.py b/tests/functional/test_changelog_basic_ansible.py index a8bd84ec..c22253ed 100644 --- a/tests/functional/test_changelog_basic_ansible.py +++ b/tests/functional/test_changelog_basic_ansible.py @@ -170,6 +170,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na notesdir: fragments prelude_section_name: release_summary new_plugins_after_name: removed_features +add_plugin_period: true sections: - ['major_changes', 'Major Changes'] - ['minor_changes', 'Minor Changes'] @@ -264,7 +265,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na assert changelog["releases"]["2.10"]["modules"] == [ { "name": "test", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "", }, ] @@ -272,7 +273,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na "lookup": [ { "name": "bar", - "description": "A foo bar lookup", + "description": "A foo bar lookup.", "namespace": None, }, ], @@ -308,12 +309,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo bar lookup +- bar - A foo bar lookup. New Modules ----------- -- test - This is a test module +- test - This is a test module. """ ) @@ -399,7 +400,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na assert changelog["releases"]["2.10"]["modules"] == [ { "name": "test", - "description": "This is a TEST module", + "description": "This is a TEST module.", "namespace": "", }, ] @@ -407,7 +408,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na "lookup": [ { "name": "bar", - "description": "A foo_bar lookup", + "description": "A foo_bar lookup.", "namespace": None, }, ], @@ -441,12 +442,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo_bar lookup +- bar - A foo_bar lookup. New Modules ----------- -- test - This is a TEST module +- test - This is a TEST module. """ ) @@ -539,7 +540,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na assert changelog["releases"]["2.10.1b1"]["modules"] == [ { "name": "test_new", - "description": "This is ANOTHER test module", + "description": "This is ANOTHER test module.", "namespace": "", }, ] @@ -569,7 +570,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na New Modules ----------- -- test_new - This is ANOTHER test module +- test_new - This is ANOTHER test module. v2.10 ===== @@ -592,12 +593,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo_bar lookup +- bar - A foo_bar lookup. New Modules ----------- -- test - This is a TEST module +- test - This is a TEST module. """ ) @@ -706,7 +707,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na assert changelog["releases"]["2.10.1"]["modules"] == [ { "name": "test_new2", - "description": "This is ANOTHER test module!!!11", + "description": "This is ANOTHER test module!!!11.", "namespace": "", }, { @@ -747,8 +748,8 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na New Modules ----------- -- test_new - This is ANOTHER test module -- test_new2 - This is ANOTHER test module!!!11 +- test_new - This is ANOTHER test module. +- test_new2 - This is ANOTHER test module!!!11. - test_new3 - This is yet another test module. v2.10 @@ -772,12 +773,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo_bar lookup +- bar - A foo_bar lookup. New Modules ----------- -- test - This is a TEST module +- test - This is a TEST module. """ ) @@ -899,6 +900,7 @@ def test_changelog_release_ansible_plugin_cache( # pylint: disable=redefined-ou notesdir: fragments prelude_section_name: release_summary new_plugins_after_name: removed_features +add_plugin_period: false sections: - ['major_changes', 'Major Changes'] - ['minor_changes', 'Minor Changes'] diff --git a/tests/functional/test_changelog_basic_ansible_classic.py b/tests/functional/test_changelog_basic_ansible_classic.py index 7fe09200..cd7cd583 100644 --- a/tests/functional/test_changelog_basic_ansible_classic.py +++ b/tests/functional/test_changelog_basic_ansible_classic.py @@ -172,6 +172,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na notesdir: fragments prelude_section_name: release_summary new_plugins_after_name: removed_features +add_plugin_period: true sections: - ['major_changes', 'Major Changes'] - ['minor_changes', 'Minor Changes'] @@ -291,12 +292,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo bar lookup +- bar - A foo bar lookup. New Modules ----------- -- test - This is a test module +- test - This is a test module. """ ) @@ -405,12 +406,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo_bar lookup +- bar - A foo_bar lookup. New Modules ----------- -- test - This is a TEST module +- test - This is a TEST module. """ ) @@ -521,7 +522,7 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na New Modules ----------- -- test_new - This is ANOTHER test module +- test_new - This is ANOTHER test module. v2.9 ==== @@ -544,12 +545,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo_bar lookup +- bar - A foo_bar lookup. New Modules ----------- -- test - This is a TEST module +- test - This is a TEST module. """ ) @@ -683,8 +684,8 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na New Modules ----------- -- test_new - This is ANOTHER test module -- test_new2 - This is ANOTHER test module!!!11 +- test_new - This is ANOTHER test module. +- test_new2 - This is ANOTHER test module!!!11. - test_new3 - This is yet another test module. v2.9 @@ -708,12 +709,12 @@ def test_changelog_release_ansible_simple( # pylint: disable=redefined-outer-na Lookup ~~~~~~ -- bar - A foo_bar lookup +- bar - A foo_bar lookup. New Modules ----------- -- test - This is a TEST module +- test - This is a TEST module. """ ) diff --git a/tests/functional/test_changelog_basic_collection.py b/tests/functional/test_changelog_basic_collection.py index f0f9592c..6897593e 100644 --- a/tests/functional/test_changelog_basic_collection.py +++ b/tests/functional/test_changelog_basic_collection.py @@ -429,7 +429,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name assert changelog["releases"]["1.0.0"]["modules"] == [ { "name": "test", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "", }, ] @@ -437,7 +437,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name "lookup": [ { "name": "bar", - "description": "A foo bar lookup", + "description": "A foo bar lookup.", "namespace": None, }, ], @@ -471,12 +471,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name Lookup ~~~~~~ -- acme.test.bar - A foo bar lookup +- acme.test.bar - A foo bar lookup. New Modules ----------- -- acme.test.test - This is a test module +- acme.test.test - This is a test module. """ ) @@ -548,7 +548,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name assert changelog["releases"]["1.0.0"]["modules"] == [ { "name": "test", - "description": "This is a TEST module", + "description": "This is a TEST module.", "namespace": "", }, ] @@ -556,7 +556,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name "lookup": [ { "name": "bar", - "description": "A foo_bar lookup", + "description": "A foo_bar lookup.", "namespace": None, }, ], @@ -589,12 +589,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name Lookup ~~~~~~ -- acme.test.bar - A foo_bar lookup +- acme.test.bar - A foo_bar lookup. New Modules ----------- -- acme.test.test - This is a TEST module +- acme.test.test - This is a TEST module. """ ) @@ -685,7 +685,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name assert changelog["releases"]["1.1.0-beta-1"]["modules"] == [ { "name": "test_new", - "description": "This is ANOTHER test module", + "description": "This is ANOTHER test module.", "namespace": "", }, ] @@ -716,7 +716,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name New Modules ----------- -- acme.test.test_new - This is ANOTHER test module +- acme.test.test_new - This is ANOTHER test module. v1.0.0 ====== @@ -738,12 +738,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name Lookup ~~~~~~ -- acme.test.bar - A foo_bar lookup +- acme.test.bar - A foo_bar lookup. New Modules ----------- -- acme.test.test - This is a TEST module +- acme.test.test - This is a TEST module. """ ) @@ -862,7 +862,7 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name assert changelog["releases"]["1.1.0"]["modules"] == [ { "name": "test_new2", - "description": "This is ANOTHER test module!!!11", + "description": "This is ANOTHER test module!!!11.", "namespace": "", }, { @@ -904,8 +904,8 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name New Modules ----------- -- acme.test.test_new - This is ANOTHER test module -- acme.test.test_new2 - This is ANOTHER test module!!!11 +- acme.test.test_new - This is ANOTHER test module. +- acme.test.test_new2 - This is ANOTHER test module!!!11. - acme.test.test_new3 - This is yet another test module. v1.0.0 @@ -928,12 +928,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name Lookup ~~~~~~ -- acme.test.bar - A foo_bar lookup +- acme.test.bar - A foo_bar lookup. New Modules ----------- -- acme.test.test - This is a TEST module +- acme.test.test - This is a TEST module. """ ) @@ -1225,8 +1225,8 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name New Modules ----------- -- acme.test.test_new - This is ANOTHER test module -- acme.test.test_new2 - This is ANOTHER test module!!!11 +- acme.test.test_new - This is ANOTHER test module. +- acme.test.test_new2 - This is ANOTHER test module!!!11. - acme.test.test_new3 - This is yet another test module. v1.0.0 @@ -1249,12 +1249,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name Lookup ~~~~~~ -- acme.test.bar - A foo_bar lookup +- acme.test.bar - A foo_bar lookup. New Modules ----------- -- acme.test.test - This is a TEST module +- acme.test.test - This is a TEST module. """ ) @@ -1347,8 +1347,8 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name New Modules ----------- -- acme.test.test_new - This is ANOTHER test module -- acme.test.test_new2 - This is ANOTHER test module!!!11 +- acme.test.test_new - This is ANOTHER test module. +- acme.test.test_new2 - This is ANOTHER test module!!!11. - acme.test.test_new3 - This is yet another test module. v1.0.0 @@ -1371,12 +1371,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name Lookup ~~~~~~ -- acme.test.bar - A foo_bar lookup +- acme.test.bar - A foo_bar lookup. New Modules ----------- -- acme.test.test - This is a TEST module +- acme.test.test - This is a TEST module. """ ) @@ -1422,8 +1422,8 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name New Modules ----------- -- acme.test.test_new - This is ANOTHER test module -- acme.test.test_new2 - This is ANOTHER test module!!!11 +- acme.test.test_new - This is ANOTHER test module. +- acme.test.test_new2 - This is ANOTHER test module!!!11. - acme.test.test_new3 - This is yet another test module. """ ) @@ -1470,12 +1470,12 @@ def test_changelog_release_simple( # pylint: disable=redefined-outer-name ### Lookup -* acme\.test\.bar \- A foo\_bar lookup +* acme\.test\.bar \- A foo\_bar lookup\. ## New Modules -* acme\.test\.test \- This is a TEST module +* acme\.test\.test \- This is a TEST module\. """ ) @@ -1714,37 +1714,37 @@ def test_changelog_release_simple_no_galaxy( # pylint: disable=redefined-outer- assert changelog["releases"]["1.0.0"]["modules"] == [ { "name": "test", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "", }, { "name": "test1", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "test", }, { "name": "test2", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "test.foo", }, { "name": "test3", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "test.bar", }, { "name": "test4", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "foo", }, { "name": "test5", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "bar.baz", }, { "name": "test6", - "description": "This is a test module", + "description": "This is a test module.", "namespace": "foo.bar.baz", }, ] @@ -1752,7 +1752,7 @@ def test_changelog_release_simple_no_galaxy( # pylint: disable=redefined-outer- "lookup": [ { "name": "bar", - "description": "A foo bar lookup", + "description": "A foo bar lookup.", "namespace": None, }, ], @@ -1786,12 +1786,12 @@ def test_changelog_release_simple_no_galaxy( # pylint: disable=redefined-outer- Lookup ~~~~~~ -- bar - A foo bar lookup +- bar - A foo bar lookup. New Modules ----------- -- test - This is a test module +- test - This is a test module. Bar ~~~ @@ -1799,32 +1799,32 @@ def test_changelog_release_simple_no_galaxy( # pylint: disable=redefined-outer- baz ^^^ -- test5 - This is a test module +- test5 - This is a test module. Foo ~~~ -- test4 - This is a test module +- test4 - This is a test module. bar.baz ^^^^^^^ -- test6 - This is a test module +- test6 - This is a test module. Test ~~~~ -- test1 - This is a test module +- test1 - This is a test module. bar ^^^ -- test3 - This is a test module +- test3 - This is a test module. foo ^^^ -- test2 - This is a test module +- test2 - This is a test module. """ ) @@ -2182,7 +2182,7 @@ def test_changelog_release_plugin_cache( # pylint: disable=redefined-outer-name assert changelog["releases"]["1.0.0"]["modules"][0]["namespace"] == "" assert ( changelog["releases"]["1.0.0"]["modules"][0]["description"] - == "A test module" + == "A test module." ) assert "version_added" not in changelog["releases"]["1.0.0"]["modules"][0] @@ -2204,12 +2204,12 @@ def test_changelog_release_plugin_cache( # pylint: disable=redefined-outer-name New Modules ----------- -- acme.test.test_module - A test module +- acme.test.test_module - A test module. New Roles --------- -- acme.test.test_role - Test role +- acme.test.test_role - Test role. """ )