Allow to generate a changelog entry without preamble for a specific version, and write it to a given filename

changelogs/fragments/131-generate.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - "Allow to write ``generate`` output to a user-provided file (https://github.com/ansible-community/antsibull-changelog/pull/131)."
+  - "Allow to generate only the last entry without preamble with the ``generate`` command (https://github.com/ansible-community/antsibull-changelog/pull/131)."

src/antsibull_changelog/changelog_generator.py

@@ -279,6 +279,7 @@ def generate_to(  # pylint: disable=too-many-arguments
         squash: bool = False,
         after_version: str | None = None,
         until_version: str | None = None,
+        only_latest: bool = False,
     ) -> None:
         """
         Append changelog to a reStructuredText (RST) builder.
@@ -287,17 +288,23 @@ def generate_to(  # pylint: disable=too-many-arguments
         :arg squash: Squash all releases into one entry
         :arg after_version: If given, only consider versions after this one
         :arg until_version: If given, do not consider versions following this one
+        :arg only_latest: If set to ``True``, only generate the latest entry
         """
         release_entries = self.collect(
             squash=squash, after_version=after_version, until_version=until_version
         )
 
         for release in release_entries:
             self.append_changelog_entry(
-                builder, release, start_level=start_level, add_version=not squash
+                builder,
+                release,
+                start_level=start_level,
+                add_version=not squash and not only_latest,
             )
+            if only_latest:
+                break
 
-    def generate(self) -> str:
+    def generate(self, only_latest: bool = False) -> str:
         """
         Generate the changelog as reStructuredText.
         """
@@ -308,24 +315,26 @@ def generate(self) -> str:
         )
 
         builder = RstBuilder()
-        title = self.config.title or "Ansible"
-        if major_minor_version:
-            title = "%s %s" % (title, major_minor_version)
-        if codename:
-            title = '%s "%s"' % (title, codename)
-        builder.set_title("%s Release Notes" % (title,))
-        builder.add_raw_rst(".. contents:: Topics\n")
-
-        if self.changes.ancestor and self.config.mention_ancestor:
-            builder.add_raw_rst(
-                "This changelog describes changes after version {0}.\n".format(
-                    self.changes.ancestor
+
+        if not only_latest:
+            title = self.config.title or "Ansible"
+            if major_minor_version:
+                title = "%s %s" % (title, major_minor_version)
+            if codename:
+                title = '%s "%s"' % (title, codename)
+            builder.set_title("%s Release Notes" % (title,))
+            builder.add_raw_rst(".. contents:: Topics\n")
+
+            if self.changes.ancestor and self.config.mention_ancestor:
+                builder.add_raw_rst(
+                    "This changelog describes changes after version {0}.\n".format(
+                        self.changes.ancestor
+                    )
                 )
-            )
-        else:
-            builder.add_raw_rst("")
+            else:
+                builder.add_raw_rst("")
 
-        self.generate_to(builder, 0)
+        self.generate_to(builder, 0, only_latest=only_latest)
 
         return builder.generate()
 
@@ -502,25 +511,32 @@ def generate_changelog(  # pylint: disable=too-many-arguments
     plugins: list[PluginDescription] | None = None,
     fragments: list[ChangelogFragment] | None = None,
     flatmap: bool = True,
+    changelog_path: str | None = None,
+    only_latest: bool = False,
 ):
     """
     Generate the changelog as reStructuredText.
 
     :arg plugins: Will be loaded if necessary. Only provide when you already have them
     :arg fragments: Will be loaded if necessary. Only provide when you already have them
-    :type flatmap: Whether the collection uses flatmapping or not
+    :arg flatmap: Whether the collection uses flatmapping or not
+    :arg changelog_path: Write the output to this path instead of the default path.
+    :arg only_latest: Only write the last changelog entry without any preamble
     """
-    major_minor_version = ".".join(
-        changes.latest_version.split(".")[: config.changelog_filename_version_depth]
-    )
-    if "%s" in config.changelog_filename_template:
-        changelog_filename = config.changelog_filename_template % (major_minor_version,)
-    else:
-        changelog_filename = config.changelog_filename_template
-    changelog_path = os.path.join(paths.changelog_dir, changelog_filename)
+    if changelog_path is None:
+        major_minor_version = ".".join(
+            changes.latest_version.split(".")[: config.changelog_filename_version_depth]
+        )
+        if "%s" in config.changelog_filename_template:
+            changelog_filename = config.changelog_filename_template % (
+                major_minor_version,
+            )
+        else:
+            changelog_filename = config.changelog_filename_template
+        changelog_path = os.path.join(paths.changelog_dir, changelog_filename)
 
     generator = ChangelogGenerator(config, changes, plugins, fragments, flatmap)
-    rst = generator.generate()
+    rst = generator.generate(only_latest=only_latest)
 
     with open(changelog_path, "wb") as changelog_fd:
         changelog_fd.write(rst.encode("utf-8"))

src/antsibull_changelog/cli.py

@@ -267,6 +267,16 @@ def create_argparser(program_name: str) -> argparse.ArgumentParser:
         help="generate changelog for this version instead of for the latest version",
         nargs="?",
     )
+    generate_parser.add_argument(
+        "--output",
+        help="write the changelog to this file instead of the default file",
+    )
+    generate_parser.add_argument(
+        "--only-latest",
+        action="store_true",
+        help="only write the changelog entry for the latest version, without a preamble."
+        " Should only be used with --output.",
+    )
 
     if HAS_ARGCOMPLETE:
         argcomplete.autocomplete(parser)
@@ -674,6 +684,8 @@ def command_generate(args: Any) -> int:
     ansible_doc_bin: str | None = args.ansible_doc_bin
     paths = set_paths(is_collection=args.is_collection, ansible_doc_bin=ansible_doc_bin)
     version: str | None = args.version
+    output: str | None = args.output
+    only_latest: bool = args.only_latest
 
     collection_details = CollectionDetails(paths)
     config = ChangelogConfig.load(paths, collection_details)
@@ -704,7 +716,16 @@ def command_generate(args: Any) -> int:
             version=changes.latest_version,
             force_reload=args.reload_plugins,
         )
-    generate_changelog(paths, config, changes, plugins, fragments, flatmap=flatmap)
+    generate_changelog(
+        paths,
+        config,
+        changes,
+        plugins,
+        fragments,
+        flatmap=flatmap,
+        changelog_path=output,
+        only_latest=only_latest,
+    )
 
     return 0
 

tests/functional/test_changelog_basic_collection.py

@@ -1274,6 +1274,54 @@ def test_changelog_release_simple(  # pylint: disable=redefined-outer-name
 """
     )
 
+    # Generate changelog for 1.1.0 only
+    assert (
+        collection_changelog.run_tool(
+            "generate",
+            [
+                "-vvv",
+                "--output",
+                "changelog-1.1.0.rst",
+                "--only-latest",
+                "1.1.0",
+            ],
+        )
+        == 0
+    )
+
+    diff = collection_changelog.diff()
+    assert diff.added_dirs == []
+    assert diff.added_files == ["changelog-1.1.0.rst"]
+    assert diff.removed_dirs == []
+    assert diff.removed_files == []
+    assert diff.changed_files == []
+
+    assert diff.file_contents["changelog-1.1.0.rst"].decode("utf-8") == (
+        r"""Release Summary
+---------------
+
+Final release of 1.1.0.
+
+Minor Changes
+-------------
+
+- A minor change.
+- Another new fragment.
+
+Bugfixes
+--------
+
+- A bugfix.
+
+New Modules
+-----------
+
+- 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.
+"""
+    )
+
 
 def test_changelog_release_simple_no_galaxy(  # pylint: disable=redefined-outer-name
     collection_changelog,