Skip to content

Commit

Permalink
docs(tutorial): Improve location of filename introduction
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.
  • Loading branch information
infinisil committed Apr 18, 2024
1 parent 212a938 commit dcf8bac
Showing 1 changed file with 4 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

0 comments on commit dcf8bac

Please sign in to comment.