Skip to content

Commit 90b75b4

Browse files
infinisiladiroiban
andauthored
docs(tutorial): Improve location of filename introduction (#586)
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. Co-authored-by: Adi Roiban <[email protected]>
1 parent 50fc1e6 commit 90b75b4

2 files changed

Lines changed: 5 additions & 4 deletions

File tree

docs/tutorial.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,13 @@ Configuration
1515
``towncrier`` keeps its config in the `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`_ ``pyproject.toml`` or a ``towncrier.toml`` file.
1616
If the latter exists, it takes precedence.
1717

18-
The most basic configuration is just telling ``towncrier`` where to look for news fragments::
18+
The most basic configuration is just telling ``towncrier`` where to look for news fragments and what file to generate::
1919

2020
[tool.towncrier]
2121
directory = "changes"
22+
# Where you want your news files to come out, `NEWS.rst` is the default.
23+
# This can be .rst or .md, towncrier's default template works with both.
24+
# filename = "NEWS.rst"
2225

2326
Which will look into "./changes" for news fragments and write them into "./NEWS.rst".
2427

@@ -32,9 +35,6 @@ If you're working on a Python project, you can also specify a package::
3235
# but if you don't keep your code in a 'src' dir, remove the
3336
# config option
3437
package_dir = "src"
35-
# Where you want your news files to come out. This can be .rst
36-
# or .md, towncrier's default template works with both.
37-
filename = "NEWS.rst"
3838

3939
By default, ``towncrier`` will look for news fragments inside your Python package, in a directory named ``newsfragments``.
4040
With this example project, it will look in ``src/myproject/newsfragments/`` for them.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
The tutorial now introduces the `filename` option in the appropriate paragraph and mentions its default value.

0 commit comments

Comments
 (0)