build: add CLI option 'filename'

Author: umarcor

docs/cli.rst

@@ -25,9 +25,9 @@ Build the combined news file from news fragments.
 
 .. option:: --draft
 
-   Only render news fragments to standard output.
-   Don't write to files, don't check versions.
-   Only renders the news fragments **without** the surrounding template.
+   Don't stage changes nor remove fragments.
+   If option ``--filename`` is provided, write the news there;
+   otherwise, render the fragments **without** the surrounding template to ``stdout``.
 
 .. option:: --name NAME
 
@@ -45,6 +45,11 @@ Build the combined news file from news fragments.
 
    Default: today's date
 
+.. option:: --filename FILENAME
+
+   Use `FILENAME` to override field ``filename`` from the configuration.
+   If used together with ``--draft``, write to ``FILENAME`` instead of ``stdout``.
+
 .. option:: --yes
 
    Do not ask for confirmations.

docs/configuration.rst

@@ -17,7 +17,7 @@ Top level keys
 ~~~~~~~~~~~~~~
 
 - ``directory`` -- If you are not storing your news fragments in your Python package, or aren't using Python, this is the path to where your newsfragments will be put.
-- ``filename`` -- The filename of your news file.
+- ``filename`` -- The filename (or pattern) of your news file.
   ``NEWS.rst`` by default.
 - ``package`` -- The package name of your project.
   (Python projects only)

docs/tutorial.rst

@@ -114,7 +114,7 @@ You should get an output similar to this::
    Loading template...
    Finding news fragments...
    Rendering news fragments...
-   Draft only -- nothing has been written.
+   Print draft to stdout only -- nothing has been written.
    What is seen below is what would be written.
 
    myproject 1.0.2 (2015-12-27)

src/towncrier/build.py

@@ -84,6 +84,12 @@ def _validate_answer(ctx: Context, param: Option, value: bool) -> bool:
     default=None,
     help="Render the news fragments using the given date.",
 )
+@click.option(
+    "--filename",
+    "filename",
+    default=None,
+    help="Write the output to the given filename pattern.",
+)
 @click.option(
     "--yes",
     "answer_yes",
@@ -107,6 +113,7 @@ def _main(
     project_name: str | None,
     project_version: str | None,
     project_date: str | None,
+    filename: str | None,
     answer_yes: bool,
     answer_keep: bool,
 ) -> None:
@@ -115,14 +122,15 @@ def _main(
     """
     try:
         return __main(
-            draft,
-            directory,
-            config_file,
-            project_name,
-            project_version,
-            project_date,
-            answer_yes,
-            answer_keep,
+            draft=draft,
+            directory=directory,
+            config_file=config_file,
+            project_name=project_name,
+            project_version=project_version,
+            project_date=project_date,
+            filename=filename,
+            answer_yes=answer_yes,
+            answer_keep=answer_keep,
         )
     except ConfigError as e:
         print(e, file=sys.stderr)
@@ -136,6 +144,7 @@ def __main(
     project_name: str | None,
     project_version: str | None,
     project_date: str | None,
+    filename: str | None,
     answer_yes: bool,
     answer_keep: bool,
 ) -> None:
@@ -238,44 +247,51 @@ def __main(
     else:
         content = rendered
 
-    if draft:
+    if draft and filename is None:
         click.echo(
-            "Draft only -- nothing has been written.\n"
+            "Print draft to stdout only -- nothing has been written.\n"
             "What is seen below is what would be written.\n",
             err=to_err,
         )
         click.echo(content)
         return
 
     click.echo("Writing to newsfile...", err=to_err)
-    news_file = config.filename
 
-    if config.single_file is False:
+    if filename is None:
+        filename = config.filename
+
+    single_file = config.single_file
+
+    if not single_file:
         # The release notes for each version are stored in a separate file.
         # The name of that file is generated based on the current version and project.
-        news_file = news_file.format(
-            name=project_name, version=project_version, project_date=project_date
+        filename = filename.format(
+            name=project_name,
+            version=project_version,
+            project_date=project_date,
         )
 
     append_to_newsfile(
         base_directory,
-        news_file,
+        filename,
         config.start_string,
         top_line,
         content,
-        single_file=config.single_file,
+        single_file=single_file,
     )
 
-    click.echo("Staging newsfile...", err=to_err)
-    _git.stage_newsfile(base_directory, news_file)
+    if not draft:
+        click.echo("Staging newsfile...", err=to_err)
+        _git.stage_newsfile(base_directory, filename)
 
-    if should_remove_fragment_files(
-        fragment_filenames,
-        answer_yes,
-        answer_keep,
-    ):
-        click.echo("Removing news fragments...", err=to_err)
-        _git.remove_files(fragment_filenames)
+        if should_remove_fragment_files(
+            fragment_filenames,
+            answer_yes,
+            answer_keep,
+        ):
+            click.echo("Removing news fragments...", err=to_err)
+            _git.remove_files(fragment_filenames)
 
     click.echo("Done!", err=to_err)
 

src/towncrier/newsfragments/489.feature

@@ -0,0 +1 @@
+Add CLI option ``--filename FILENAME``.

src/towncrier/test/test_build.py

@@ -60,7 +60,7 @@ def _test_command(self, command):
                 Loading template...
                 Finding news fragments...
                 Rendering news fragments...
-                Draft only -- nothing has been written.
+                Print draft to stdout only -- nothing has been written.
                 What is seen below is what would be written.
 
                 Foo 1.2.3 (01-01-2001)
@@ -273,7 +273,7 @@ def run_order_scenario(sections, types):
         self.assertEqual(
             result.output,
             "Loading template...\nFinding news fragments...\nRendering news "
-            "fragments...\nDraft only -- nothing has been written.\nWhat is "
+            "fragments...\nPrint draft to stdout only -- nothing has been written.\nWhat is "
             "seen below is what would be written.\n\nFoo 1.2.3 (01-01-2001)"
             "\n======================"
             + dedent(
@@ -316,7 +316,7 @@ def run_order_scenario(sections, types):
         self.assertEqual(
             result.output,
             "Loading template...\nFinding news fragments...\nRendering news "
-            "fragments...\nDraft only -- nothing has been written.\nWhat is "
+            "fragments...\nPrint draft to stdout only -- nothing has been written.\nWhat is "
             "seen below is what would be written.\n\nFoo 1.2.3 (01-01-2001)"
             "\n======================"
             + dedent(
@@ -551,7 +551,7 @@ def test_projectless_changelog(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             FooBarBaz 7.8.9 (01-01-2001)
@@ -592,7 +592,7 @@ def test_version_in_config(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             7.8.9 (01-01-2001)
@@ -634,7 +634,7 @@ def test_project_name_in_config(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             ImGoProject 7.8.9 (01-01-2001)
@@ -679,7 +679,7 @@ def test_no_package_changelog(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             7.8.9 (01-01-2001)
@@ -1010,7 +1010,7 @@ def test_title_format_custom(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             [20-01-2001] CUSTOM RELEASE for FooBarBaz version 7.8.9
@@ -1087,7 +1087,7 @@ def test_title_format_false(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             Here's a hardcoded title added by the template
@@ -1220,7 +1220,7 @@ def test_with_topline_and_template_and_draft(self):
             Loading template...
             Finding news fragments...
             Rendering news fragments...
-            Draft only -- nothing has been written.
+            Print draft to stdout only -- nothing has been written.
             What is seen below is what would be written.
 
             7.8.9 - 20-01-2001