Skip to content

Commit

Permalink
docs(tutorial): Improve location of filename introduction (#586)
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
infinisil and adiroiban authored Apr 28, 2024
1 parent 50fc1e6 commit 90b75b4
Show file tree
Hide file tree
Showing 2 changed files with 5 additions and 4 deletions.
8 changes: 4 additions & 4 deletions docs/tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,13 @@ Configuration
``towncrier`` keeps its config in the `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`_ ``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".

Expand All @@ -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.
Expand Down
1 change: 1 addition & 0 deletions src/towncrier/newsfragments/586.doc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The tutorial now introduces the `filename` option in the appropriate paragraph and mentions its default value.

0 comments on commit 90b75b4

Please sign in to comment.