From 82a33e262c5500d5310998156feb350998c7af28 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 15 Apr 2024 18:19:26 +0200 Subject: [PATCH] docs(tutorial): Improve location of filename introduction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently, the tutorial contains this part: > The most basic configuration is just telling towncrier where to look for news fragments: > > ```toml > [tool.towncrier] > directory = "changes" > ``` > > Which will look into “./changes” for news fragments and write them into “./NEWS.rst”. Note the `and write them into “./NEWS.rst”.`. This confused me when reading, because while I clearly saw how `./changes` was specified, it's not clear why `./NEWS.rst` would be used. Only after reading the next paragraph the connection can be made, but that section is about Python specifically: > If you’re working on a Python project, you can also specify a package: > > ```toml > [tool.towncrier] > # The name of your Python package > package = "myproject" > # The path to your Python package. > # If your package lives in 'src/myproject/', it must be 'src', > # but if you don't keep your code in a 'src' dir, remove the > # config option > package_dir = "src" > # Where you want your news files to come out. This can be .rst > # or .md, towncrier's default template works with both. > filename = "NEWS.rst" > ``` But there it's very easy to miss. This commit moves the introduction of the filename option to the earlier section to avoid such confusion. Furthermore we indicate that there's no need to set the option because there's a default. --- docs/tutorial.rst | 8 ++++---- src/towncrier/newsfragments/586.doc | 1 + 2 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 src/towncrier/newsfragments/586.doc diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 875ed1f3..75f99cf0 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -15,10 +15,13 @@ Configuration ``towncrier`` keeps its config in the `PEP-518 `_ ``pyproject.toml`` or a ``towncrier.toml`` file. If the latter exists, it takes precedence. -The most basic configuration is just telling ``towncrier`` where to look for news fragments:: +The most basic configuration is just telling ``towncrier`` where to look for news fragments and what file to generate:: [tool.towncrier] directory = "changes" + # Where you want your news files to come out, `NEWS.rst` is the default. + # This can be .rst or .md, towncrier's default template works with both. + # filename = "NEWS.rst" Which will look into "./changes" for news fragments and write them into "./NEWS.rst". @@ -32,9 +35,6 @@ If you're working on a Python project, you can also specify a package:: # but if you don't keep your code in a 'src' dir, remove the # config option package_dir = "src" - # Where you want your news files to come out. This can be .rst - # or .md, towncrier's default template works with both. - filename = "NEWS.rst" By default, ``towncrier`` will look for news fragments inside your Python package, in a directory named ``newsfragments``. With this example project, it will look in ``src/myproject/newsfragments/`` for them. diff --git a/src/towncrier/newsfragments/586.doc b/src/towncrier/newsfragments/586.doc new file mode 100644 index 00000000..cbaf3461 --- /dev/null +++ b/src/towncrier/newsfragments/586.doc @@ -0,0 +1 @@ +The tutorial now introduces the `filename` option in the appropriate paragraph and mentions its default value.