diff --git a/docs/cli.rst b/docs/cli.rst index 22697d01..f81d076d 100644 --- a/docs/cli.rst +++ b/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. diff --git a/docs/configuration.rst b/docs/configuration.rst index bd0fd7ee..629f9dd1 100644 --- a/docs/configuration.rst +++ b/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) diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 7b893b1d..c6998a43 100644 --- a/docs/tutorial.rst +++ b/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) diff --git a/src/towncrier/build.py b/src/towncrier/build.py index b5477f72..2a8b73d3 100644 --- a/src/towncrier/build.py +++ b/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,9 +247,9 @@ 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, ) @@ -248,34 +257,41 @@ def __main( 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) diff --git a/src/towncrier/newsfragments/489.feature b/src/towncrier/newsfragments/489.feature new file mode 100644 index 00000000..997fbafe --- /dev/null +++ b/src/towncrier/newsfragments/489.feature @@ -0,0 +1 @@ +Add CLI option ``--filename FILENAME``. diff --git a/src/towncrier/test/test_build.py b/src/towncrier/test/test_build.py index 0a76d916..2b282171 100644 --- a/src/towncrier/test/test_build.py +++ b/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