sphinx-contrib / sphinxcontrib-towncrier Goto Github PK

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version. Demo: https://ansible-pylibssh.rtfd.io/changelog. Docs: https://sphinxcontrib-towncrier.rtfd.io

Home Page: https://pypi.org/p/sphinxcontrib-towncrier

License: BSD 3-Clause "New" or "Revised" License

Python 100.00%

sphinx sphinx-doc sphinx-extension hacktoberfest

sphinxcontrib-towncrier's Introduction

GitHub Actions CI/CD build status — Python package

sphinxcontrib-towncrier

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version.

How to use this?

$ pip install sphinxcontrib-towncrier

extensions = ['sphinxcontrib.towncrier.ext']

# Options: draft/sphinx-version/sphinx-release
towncrier_draft_autoversion_mode = 'draft'
towncrier_draft_include_empty = True
towncrier_draft_working_directory = PROJECT_ROOT_DIR
# Not yet supported:
# towncrier_draft_config_path = 'pyproject.toml'  # relative to cwd

Make sure to point to the dir with pyproject.toml and pre-configure towncrier itself in the config.

If everything above is set up correctly, you should be able to add

.. towncrier-draft-entries::

to your documents, like changelog.rst. With no argument, the version title will be generated using the strategy set up in the towncrier_draft_autoversion_mode setting.

If you want to be in control, override it with an argument you like:

.. towncrier-draft-entries:: |release| [UNRELEASED DRAFT]

Native RST substitutions in the argument work, just make sure to declare any non-default ones via rst_epilog or at the end of the document where the towncrier-draft-entries directive is being used.

Does anybody actually use this?

So far we know about two projects using sphinxcontrib-towncrier — ansible/pylibssh and pypa/pip. Also, this Sphinx extension is inspired by and somewhat based on the ideas used in pytest-dev/pytest and tox-dev/tox. We believe that these projects are full of wonderful tricks that you may want to explore regardless of whether you'll use our project.

sphinxcontrib-towncrier's People

Contributors

Stargazers

Watchers

Forkers

slsh1o ewjoachim webknjaz admdev8 global-localhost global19 global19-atlassian-net ssbarnea uranusjr gaborbernat davfsa ericpre l1storez q0w dvzrv mcflugen jaraco sysfce2

sphinxcontrib-towncrier's Issues

Error in get_outdated_docs when framents dir missing

Towncrier runs fine if the newsfragments directory doesn't exist.

This plugin will fail if the directory doesn't exist with this error:

Extension error (sphinxcontrib.towncrier.ext):
Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.ext.TowncrierDraftEntriesEnvironmentCollector object at 0x1075c3990>> for event 'env-get-outdated' threw an exception (exception: Failed to list the news fragment files.
FileNotFoundError: [Errno 2] No such file or directory: '../newsfragments/'
)

This plugin should honor the degenerate newsfragments including no directory, same as towncrier.

📦 Add packaging-related configs

First of all, we'll be using a pure setuptools-based setup wrapped with PEP517.
Here's where you can learn a bit about producing Python package distributions: https://packaging.python.org/tutorials/packaging-projects/. Also, here's some pointers to what configuration options setuptools provides: https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files.
See also: https://youtu.be/GaWs-LenLYE.

While the tutorial showcases the use of setup.py, I'd like us to start without it and use setup.cfg instead. Please start by mimicking these:

Note, that there's no version hardcoded. This is because there's setuptools-scm configured. Make sure to keep it in the configs and don't copy things that are not related to this task.

Use sphinxcontrib-towncrier as a dist name in setup.cfg.

Self-check

After adding these files, you can test that the setup works with a clean virtualenv by running:

# test 1:
$ python -m pip wheel .  # this will just build a single wheel under the `dist/` dir
# test 2:
$ python -m pip install pep517  # this installs a library that implements a PEP517 build front-end
$ python -m pep517.build --binary --source --out-dir dist .  # this will produce both wheel and a source dist (.tar.gz)

If nothing explodes, you've probably added all essential configs.

For each of the tests, you can also try unpacking the dists and checking what's inside:

$ python -m wheel unpack dist/WHELL_NAME.whl  # to get the contents of WHELL_NAME.whl
$ tar xzvf dist/SDIST_NAME.tar.gz  # to see what's inside the sdist

Finally, try installing them and do an import smoke-test:

$ python -m pip install dist/WHELL_NAME.whl  # for the wheel
$ python -m pip install dist/SDIST_NAME.tar.gz  # for the sdist
$ python -m pip install .  # for the current project directory
$ python -c 'from sphinxcontrib.towncrier import TowncrierDraftEntriesDirective, setup'

EncodingWarning

I see this warning when running the docs build for setuptools:

/Users/jaraco/code/pypa/setuptools/.tox/docs/lib/python3.12/site-packages/sphinxcontrib/towncrier/ext.py:66: EncodingWarning: 'encoding' argument not specified.
  towncrier_output = subprocess.check_output(  # noqa: S603

Broken `fragment_base_directory` fallback in `_lookup_towncrier_fragments`

Looking at the source I noticed a weird try/except with identical code in the fallback part at https://github.com/sphinx-contrib/sphinxcontrib-towncrier/blob/3dcf71a/src/sphinxcontrib/towncrier/__init__.py#L106-L108. I think the except block meant to use fragment_directory.

Convert README.md into RST format

While markdown is already supported by PyPI, it'll be easier to seamlessly embed README into our docs in the future, once it's in RST.

Rename this repo to towncrier?

According to https://github.com/sphinx-contrib/github-administration:

rename the repository to remove prefixes like sphinx, sphinx-contrib, and sphinxcontrib. Don't forget to update the documentation in the repository, too!

Implement fragment-dependent cache invalidation in Sphinx for RST documents using the extension

To speed-up sequential builds, Sphinx caches documents as doctrees. This cache is based on whether the tracked RST files have changed and does not know anything about the changes in the directive output.
So including this directive into the document may result in it not picking up the new change fragments.

We need to explicitly document this and add some pointers on how to force rebuilds.

This idea is coming from ansible/pylibssh#120 as reported by @ewjoachim.

Contribute code as PR for review

I'd expect the first batch to be a PR so can comment on the code inline 🤔

✨ [FR] Add a directive that outputs the configured change note categories

I was writing contributing docs about Towncrier new fragments and realized that it's PITA to maintain a copy of pyproject.toml entries and not to forget to update entries in Sphinx documents on any change.

So I think it'd be a great addition to what the extension already does. Although, it's not urgent and I'd rather postpone implementing it until the dev/test/packaging/publishing tooling/infra is set up at least. For now, I just wanted to record the idea on the tracker.

✨ [FR] Add a setting for custom "empty changelog" markers

The current implementation relies on checking whether the string "No significant changes" is present in the command output: https://github.com/sphinx-contrib/sphinxcontrib-towncrier/blob/e58f24c/src/sphinxcontrib/towncrier/__init__.py#L78.

That check is hardcoded but, in fact, this output may be different if the user decides to throw in a custom changelog template. That is why we need a setting in conf.py that would allow end-users to also override the checked phrase.

Make `towncrier_draft_working_directory` relative to `conf.py`

Ref: pypa/setuptools#2677 (comment)

Add testing infrastructure

Configure pytest with a few essential plugins. e.g. https://github.com/ansible/pylibssh/blob/830218bf59c10e0a265638943878c3b13d46ca1d/pytest.ini
Set up tox to run pytest allowing to pass extra args via {posargs}. e.g. https://github.com/ansible/pylibssh/blob/830218bf59c10e0a265638943878c3b13d46ca1d/tox.ini#L11-L43
Add a very basic test infra. e.g. https://github.com/ansible/pylibssh/blob/830218bf59c10e0a265638943878c3b13d46ca1d/tests/unit/version_test.py#L15-L17
Pro tip: Start with just one test function having only assert True. This will allow you to check that you've configured all of the other bits correctly. Your goal is to see this test in the report and have it green.
Add a GHA workflow for running the tests. e.g. https://github.com/ansible/pylibssh/blob/830218bf59c10e0a265638943878c3b13d46ca1d/.github/workflows/build-test-n-publish.yml#L656
Start small, with one job. Then, extend it to be a matrix across different Python versions (as specified in setup.cfg) and OSs.
Finally, add a few unit tests for helper functions in the extension.
Add heavier integration tests too.

[TODO] Add `Towncrier ~= 23.6.0` to the CI test matrix

$sbj.

⚙ Configure pre-commit tool

We can now start configuring linting-related things.

Please take as a base these:

https://github.com/ansible/pylibssh/blob/devel/.pre-commit-config.yaml
https://github.com/ansible/ansible-lint/blob/master/.pre-commit-config.yaml#L37-L43
https://github.com/ansible/ansible-lint/blob/master/.yamllint (but turn consistent to false)
https://github.com/ansible/pylibssh/blob/devel/.darglint
https://github.com/ansible/pylibssh/blob/devel/.isort.cfg
https://github.com/ansible/pylibssh/blob/devel/.flake8
https://github.com/ansible/ansible-lint/blob/master/mypy.ini / https://github.com/sanitizers/octomachinery/blob/master/mypy.ini / https://github.com/ansible/ansible-lint/blob/master/.pre-commit-config.yaml#L60-L67
https://github.com/ansible/ansible-lint/blob/master/.pre-commit-config.yaml#L68-L71 / https://github.com/sanitizers/octomachinery/blob/master/.pre-commit-config.yaml#L51-L58 / https://github.com/sanitizers/octomachinery/blob/master/.pylintrc (generate the base config via pylint --generate-rcfile > .pylintrc and only then borrow things from examples, only if necessary, in separate commits, for comparison)

Since it's a lot of changes, feel free to submit separate PRs with small changes.

[FR] Support running towncrier in isolated mode

I have a project which includes some C extensions, built in an isolated environment via PEP-517. This means that the source tree never has a compiled version of the C extensions in it, only the built wheel has those. This makes it impossible to import the package from the source root. When sphinxcontrib-towncrier runs "python -m towncrier" this automatically adds the current directory to the system path, resulting in a failure of towncrier to import the module. This can be fixed by telling Python to run the module isolated "python -Im towncrier ...". Would you consider supporting this paradigm, perhaps as a configurable option? I am happy to put together a PR if the proposal is acceptable.
Thanks.

Allow lower version of importlib_metadata

As you might aware, flake8 pins the version of importlib_metadata to importlib-metadata<4.3 for python 3.7 with no plan to remove this. As far as I can see, you only use it for "version", so could you relax the minimal version required?

I'm happy to provide a PR for this

Support finding `towncrier.toml` automatically

The configuration of towncrier can also be placed in a dedicated configuration file named towncrier.toml with the same syntax, which is meant to be stored in the same place of pyproject.toml and takes precedence over it.

It seems to me that this package doesn't respect this, and looks only at pyproject.toml:

WARNING: Missing key 'towncrier' in file XXXX/docs/source/../../pyproject.toml

Dict-access to towncrier's Config objects breaks with Towncrier 22.12

See twisted/towncrier#461 or https://github.com/python-attrs/attrs/actions/runs/3755544183/jobs/6380710259#step:7:39

Config has become a data class in the last release and it's all my fault, sorry.

sphinxcontrib-towncrier/src/sphinxcontrib/towncrier/ext.py

Lines 132 to 143 in 12362b5

    
               fragment_base_directory = project_path / towncrier_config['directory'] 
        
           except KeyError: 
        
               assert fragment_directory is not None 
        
               fragment_base_directory = project_path / fragment_directory 
        
           else: 
        
               fragment_directory = None 
        
           _fragments, fragment_filenames = find_fragments( 
        
               base_directory=str(fragment_base_directory), 
        
               fragment_directory=fragment_directory, 
        
               definitions=towncrier_config['types'], 
        
               sections=towncrier_config['sections'],

0.2.0a0: pytest is failing

Looks like pytest is failing because it cannot find in project root sphinxcontrib.towncrier.
Probably move src/sphinxcontrib/ to sphinxcontrib/ may help.

+ /usr/bin/python3 -Bm pytest -ra
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.9, pytest-6.2.4, py-1.10.0, pluggy-0.13.1 -- /usr/bin/python3
cachedir: .pytest_cache
hypothesis profile 'default' -> database=DirectoryBasedExampleDatabase('/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/.hypothesis/examples')
rootdir: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0, configfile: pytest.ini, testpaths: tests/
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, expect-1.1.0, httpbin-1.0.0, xdist-2.2.1, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, freezegun-0.4.2, cases-3.4.6, case-1.5.3, isort-1.3.0, aspectlib-1.5.2, asyncio-0.15.1, toolbox-0.5, xprocess-0.17.1, aiohttp-0.3.0, checkdocs-2.7.0, mock-3.6.1, rerunfailures-9.1.1, requests-mock-1.9.3, Faker-8.4.0, cov-2.12.1, pyfakefs-4.5.0, hypothesis-6.13.14
[gw0] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw1] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw2] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw3] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw4] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw5] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw6] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw7] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw8] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw9] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw10] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw11] linux Python 3.8.9 cwd: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0
[gw0] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw1] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw2] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw3] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw4] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw5] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw6] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw7] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw8] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw9] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw11] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
[gw10] Python 3.8.9 (default, Apr  7 2021, 13:42:48)  -- [GCC 11.0.1 20210324 (Red Hat 11.0.1-0)]
gw0 [0] / gw1 [0] / gw2 [0] / gw3 [0] / gw4 [0] / gw5 [0] / gw6 [0] / gw7 [0] / gw8 [0] / gw9 [0] / gw10 [0] / gw11 [0]
scheduling tests via LoadScheduling

================================================================================== ERRORS ==================================================================================
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f0159358310>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f0159358310>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
ImportError while importing test module '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/lib64/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fc3856c32b0>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fc3856c32b0>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fa8013922e0>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fa8013922e0>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f919774f2b0>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f919774f2b0>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fe459e11250>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fe459e11250>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7ff653a01250>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7ff653a01250>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f205f4b72b0>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f205f4b72b0>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f35ff1b9280>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f35ff1b9280>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f79a973e2b0>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f79a973e2b0>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f945b5271f0>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7f945b5271f0>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fca83eb7280>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fca83eb7280>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
__________________________________________________________________ ERROR collecting tests/version_test.py __________________________________________________________________
tests/version_test.py:2: in <module>
    from sphinxcontrib.towncrier import __version__
E   ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
        __builtins__ = <builtins>
        __cached__ = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/__pycache__/version_test.cpython-38.pyc'
        __doc__    = 'Version tests.'
        __file__   = '/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py'
        __loader__ = <_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fb7d39d3280>
        __name__   = 'version_test'
        __package__ = ''
        __spec__   = ModuleSpec(name='version_test', loader=<_pytest.assertion.rewrite.AssertionRewritingHook object at 0x7fb7d39d3280>, origin='/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/tests/version_test.py')
---------------------------- generated xml file: /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/.test-results/pytest/results.xml ----------------------------
========================================================================= short test summary info ==========================================================================
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
ERROR tests/version_test.py - ModuleNotFoundError: No module named 'sphinxcontrib.towncrier'
============================================================================ 13 errors in 5.07s ============================================================================

🐛 Add missing `setuptools_scm_git_archive` configuration bits

Examples:

Suppress output from towncrier's stderr

With the current pip main branch, the Sphinx build output is clobbered by the output from towncrier:

updating environment: [new config] 66 added, 0 changed, 0 removed
Loading template...[ 54%] news                                                                                                                          
Finding news fragments...
Rendering news fragments...
Draft only -- nothing has been written.
What is seen below is what would be written.

reading sources... [100%] ux_research_design

This is sub-optimal, and it's likely safe to capture the towncrier's stderr and suppress it unless towncrier errors out.

🚚 Replace old repo links with the new ones in the source code

In the light of #5, we need to track down all of the references to https://github.com/sphinx-contrib/towncrier and replace them with https://github.com/sphinx-contrib/sphinxcontrib-towncrier.

0.2.0a0: no docs/ in pypi dist tar ball

Looks like docs/ content is not included in pypi dist tar ball.

Add a `lint` toxenv to the config

Example: https://github.com/ansible/pylibssh/blob/eb35bc2/tox.ini#L233-L246

This task is about the same as #19.

Add a GitHub Actions workflow that runs linting-related toxenvs

This task depends on #19 and #20 being implemented first (and probably some small part of #16)

The idea is to add something like https://github.com/ansible/pylibssh/blob/eb35bc2/.github/workflows/tox-linters.yml having jobs for running lint (#20) and build-dists (#19) envs.

P.S. I'd prefer to use an "output" for interpreter hash as in https://github.com/ansible/pylibssh/blob/eb35bc2/.github/workflows/build-test-n-publish.yml#L278-L289 instead of the env var.

N.B. You may want to take a look at https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions if something doesn't work.

Create a tox config with `build-dists` env in it

Here's an example: https://github.com/sanitizers/octomachinery/blob/f0b90bb/tox.ini#L77-L96.

The goal is to be able to run tox -e build-dists that would produce dists under the dist/ folder.

The example doesn't have it but please also add a description value for the corresponding section. You may check how it's being displayed by running tox -av.

Use the commands mentioned above as a self-check.

Error in get_outdated_docs when directory is not specified

Towncrier uses the directory newsfragments by default. However, if directory is not defined in the towncrier config, this plugin will fail with the following error:

Extension error (sphinxcontrib.towncrier.ext):
Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.ext.TowncrierDraftEntriesEnvironmentCollector object at 0x107773750>> for event 'env-get-outdated' threw an exception (exception: unsupported operand type(s) for /: 'PosixPath' and 'NoneType')

Adding directory = "newsfragments" to the config works around the error.

This extension should support the same defaults as towncrier.

Make Sphinx doctree cache invalidation also depend on the Jinja 2 template changes

Currently, changes to the file specified in [tool.towncrier].template, in pyproject.toml or towncrier.toml don't cause rebuilding the document where our directive is used. I mean, updating any of the template file or the config file doesn't invalidate the doctrees cache, at the moment.
This problem existed for the change fragments too, in the past. And have been addressed via #1, #8 and #23.

Now, the same has to be done for the template too.

0.2.0a0 + master: build_sphings warnings and some other issues with building socumentation

First just "setup.py build"
Than :

+ PYTHONPATH=$PWD/build/lib SETUPTOOLS_SCM_PRETEND_VERSION=0.2.0a0 /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.2
loading translations [en]... done

Extension error:
Could not import extension sphinxcontrib.towncrier (exception: No module named 'sphinxcontrib.towncrier')

I've checked that with strace and:

openat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", O_RDONLY|O_NONBLOCK|O_CLOEXEC|O_DIRECTORY) = 3
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", {st_mode=S_IFDIR|0755, st_size=26, ...}, 0) = 0
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", {st_mode=S_IFDIR|0755, st_size=26, ...}, 0) = 0
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib", {st_mode=S_IFDIR|0755, st_size=26, ...}, 0) = 0
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.cpython-38-x86_64-linux-gnu.so", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.abi3.so", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.so", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.py", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib/__init__.pyc", 0x7ffd845bbfd0, 0) = -1 ENOENT (No such file or directory)
newfstatat(AT_FDCWD, "/home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/build/lib/sphinxcontrib", {st_mode=S_IFDIR|0755, st_size=18, ...}, 0) = 0

So I've added > build/lib/sphinxcontrib/__init__.py to create empty file for which is loooking sphinx and documentation builds but with some warnings:

+ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.0.2
loading translations [en]... done
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.rtfd.io/en/stable/objects.inv...
loading intersphinx inventory from https://setuptools.rtfd.io/en/latest/objects.inv...
loading intersphinx inventory from https://www.sphinx-doc.org/en/master/objects.inv...
intersphinx inventory has moved: https://docs.rtfd.io/en/stable/objects.inv -> https://docs.readthedocs.io/en/stable/objects.inv
intersphinx inventory has moved: https://setuptools.rtfd.io/en/latest/objects.inv -> https://setuptools.readthedocs.io/en/latest/objects.inv
myst v0.15.1: MdParserConfig(renderer='sphinx', commonmark_only=False, enable_extensions=['dollarmath'], dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', disable_syntax=[], url_schemes=['http', 'https', 'mailto', 'ftp'], heading_anchors=None, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier._scm_version.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier._towncrier.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/sphinxcontrib.towncrier._version.rst.
Creating file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/docs/pkg/modules.rst.
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] pkg/sphinxcontrib.towncrier._version
WARNING: Missing key 'towncrier' in file /home/tkloczko/rpmbuild/BUILD/sphinxcontrib-towncrier-0.2.0a0/pyproject.toml
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... sphinxcontrib-towncrier.1 { change-notes-layout contributing pkg/modules pkg/sphinxcontrib pkg/sphinxcontrib.towncrier pkg/sphinxcontrib.towncrier._scm_version pkg/sphinxcontrib.towncrier._towncrier pkg/sphinxcontrib.towncrier._version } done
build succeeded, 1 warning.

[FR] Add support for Towncriers new config format

Towncrier 22.8 added support for a new way of configuring custom types see https://github.com/twisted/towncrier/blob/trunk/NEWS.rst#features and twisted/towncrier#369

When I use that with [sphinxcontrib-towncrier](https://github.com/sphinx-contrib/sphinxcontrib-towncrier) non of my changes are included in the prerelease docs file which just reads no significant changes It would be great if support can be added for this

`towncrier` 22.8.0rc1 breaks `sphinxcontrib-towncrier`

It seems that some import changes in towncrier 22.8.0:

Running Sphinx v5.1.1

Extension error:
Could not import extension sphinxcontrib.towncrier (exception: cannot import name 'load_config_from_file' from 'towncrier._settings' (C:\Users\M0041User\mambaforge\lib\site-packages\towncrier\_settings\__init__.py))

🚚 Rename the repo

Hey there :) long time no see :p

I know we already kinda had this discussion, but the more I dig into it the more pressing the issue is.

Arguments for renaming:

You can't clone both this towncrier and the other towncrier locally without renaming one of them
If you try forking both on GitHub... Not even sure you can.
If I say "towncrier" in the issues or PRs of this repo, it's suddenly unclear whether I'm speaking about towncrier or towncrier.
People might find this repo on Google while looking for towncrier. And if they don't really know what sphinx is, good luck for understanding what mess they're in.

Arguments for keeping (I'm probably missing many):

Github full slug "sphinx-contrib/towncrier" mentions that it's sphinx-related
sphinx-contrib repos are not supposed to be "sphinx-" something

Propositions:

towncrier-directive
towncrier-draft
towncrier-integration
towncrier-extension
towncrier-ext
towncrier-actually-whatever-as-long-as-it's-not-just-towncrier-:p

Incompatible with Towncrier 24.7

Looks like the just-released Towncrier 24.7 has broken some API you're using:

Running Sphinx v7.4.7
loading translations [en]... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'smartquotes', 'colon_fence', 'deflist'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 16 source files that are out of date

Traceback (most recent call last):
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/events.py", line 98, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinxcontrib/towncrier/ext.py", line 306, in get_outdated_docs
    towncrier_fragment_paths = lookup_towncrier_fragments(
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinxcontrib/towncrier/_fragment_discovery.py", line 78, in lookup_towncrier_fragments
    _fragments, fragment_filenames = find_fragments(
                                     ^^^^^^^^^^^^^^^
TypeError: find_fragments() takes 3 positional arguments but 4 were given

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/cmd/build.py", line 337, in build_main
    app.build(args.force_all, args.filenames)
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/application.py", line 378, in build
    self.builder.build_update()
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 297, in build_update
    self.build(to_build,
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 318, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 389, in read
    for docs in self.events.emit('env-get-outdated', self.env, added, changed, removed):
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/hynek/FOSS/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/events.py", line 109, in emit
    raise ExtensionError(
sphinx.errors.ExtensionError: Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.ext.TowncrierDraftEntriesEnvironmentCollector object at 0x10583e180>> for event 'env-get-outdated' threw an exception (exception: find_fragments() takes 3 positional arguments but 4 were given)

Extension error (sphinxcontrib.towncrier.ext):
Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.ext.TowncrierDraftEntriesEnvironmentCollector object at 0x10583e180>> for event 'env-get-outdated' threw an exception (exception: find_fragments() takes 3 positional arguments but 4 were given)

See https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:29 for full CI failure.

[8](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:29)
docs: commands[0]> sphinx-build -n -T -W -b html -d /home/runner/work/attrs/attrs/.tox/docs/tmp/doctrees docs docs/_build/html
[29](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:30)
Running Sphinx v7.4.7
[30](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:31)
loading translations [en]... done
[31](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:32)
making output directory... done
[32](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:33)
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
myst v3.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'smartquotes', 'colon_fence', 'deflist'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
[34](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:35)
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv...
[35](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:36)
building [mo]: targets for 0 po files that are out of date
[36](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:37)
writing output... 
[37](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:38)
building [html]: targets for 16 source files that are out of date
[38](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:39)

[39](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:40)
Traceback (most recent call last):
[40](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:41)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/events.py", line 98, in emit
[41](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:42)
    results.append(listener.handler(self.app, *args))
[42](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:43)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[43](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:44)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinxcontrib/towncrier/ext.py", line 306, in get_outdated_docs
[44](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:45)
    towncrier_fragment_paths = lookup_towncrier_fragments(
[45](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:46)
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
[46](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:47)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinxcontrib/towncrier/_fragment_discovery.py", line 78, in lookup_towncrier_fragments
[47](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:48)
    _fragments, fragment_filenames = find_fragments(
[48](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:49)
                                     ^^^^^^^^^^^^^^^
[49](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:50)
TypeError: find_fragments() takes 3 positional arguments but 4 were given
[50](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:51)

[51](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:52)
The above exception was the direct cause of the following exception:
[52](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:53)

[53](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:54)
Traceback (most recent call last):
[54](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:55)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/cmd/build.py", line 337, in build_main
[55](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:56)
    app.build(args.force_all, args.filenames)
[56](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:57)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/application.py", line 378, in build
[57](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:58)
    self.builder.build_update()
[58](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:59)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 297, in build_update
[59](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:60)
    self.build(to_build,
[60](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:61)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 318, in build
[61](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:62)
    updated_docnames = set(self.read())
[62](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:63)
                           ^^^^^^^^^^^
[63](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:64)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 389, in read
[64](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:65)
    for docs in self.events.emit('env-get-outdated', self.env, added, changed, removed):
[65](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:66)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[66](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:67)
  File "/home/runner/work/attrs/attrs/.tox/docs/lib/python3.12/site-packages/sphinx/events.py", line 109, in emit
[67](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:68)
    raise ExtensionError(
[68](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:69)
sphinx.errors.ExtensionError: Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.ext.TowncrierDraftEntriesEnvironmentCollector object at 0x7faecfa3a510>> for event 'env-get-outdated' threw an exception (exception: find_fragments() takes 3 positional arguments but 4 were given)
[69](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:70)

[70](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:71)
Extension error (sphinxcontrib.towncrier.ext):
[71](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:72)
Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.ext.TowncrierDraftEntriesEnvironmentCollector object at 0x7faecfa3a510>> for event 'env-get-outdated' threw an exception (exception: find_fragments() takes 3 positional arguments but 4 were given)
[72](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:73)
updating environment: docs: exit 2 (2.45 seconds) /home/runner/work/attrs/attrs> sphinx-build -n -T -W -b html -d /home/runner/work/attrs/attrs/.tox/docs/tmp/doctrees docs docs/_build/html pid=1877
[73](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:74)
.pkg: _exit> python /opt/hostedtoolcache/Python/3.12.4/x64/lib/python3.12/site-packages/pyproject_api/_backend.py True hatchling.build
[74](https://github.com/python-attrs/attrs/actions/runs/10176118290/job/28144823882#step:6:75)
docs: FAIL ✖ in 3.83 seconds

Towncrier 19.9 compatibility

Towncrier changed internals nad now the extension errors with

Extension error:
Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.TowncrierDraftEntriesEnvironmentCollector object at 0x10fb098b0>>
for event 'env-get-outdated' threw an exception
(exception: load_config_from_file() missing 1 required positional argument: 'config_file')

Add a warning when Towncrier template does not have `{{ top_line }}`

0.2.0a0: problem with build setuptools documentation

I,m trying to build setuptools documentation as man page.
setuoptools has project.toml file in its root directory however look slike sphinxcontrib-towncrier` has some difficulties with find that file.

[tkloczko@barrel setuptools-57.2.0]$ SETUPTOOLS_SCM_PRETEND_VERSION=57.2.0 /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx                           running build_sphinx
Running Sphinx v4.1.2
loading intersphinx inventory from https://pypa-build.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.python.org/2/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment:
Extension error (sphinxcontrib.towncrier):
Handler <bound method TowncrierDraftEntriesEnvironmentCollector.get_outdated_docs of <sphinxcontrib.towncrier.TowncrierDraftEntriesEnvironmentCollector object at 0x7f399716ae80>> for event 'env-get-outdated' threw an exception (exception: [Errno 2] No such file or directory: '../pyproject.toml')
[tkloczko@barrel setuptools-57.2.0]$

🔥 Remove scm version fallbacks from the extension

(Just to make it clear, I'm talking about the runtime dependency to setuptools-scm in the lib, not whatever you'll use to package the lib itself)

setuptools_scm definitely works, but it's kinda strange to use a tool that's linked to setuptools for extracting the version

dunamai is a library that does the same with more flexibility (as far as I can tell), is less linked to a very specific way of packaging, and is expressly made to be used as a lib.

I'd say it's worth exploring :)

	fragment_base_directory = project_path / towncrier_config['directory']
	except KeyError:
	assert fragment_directory is not None
	fragment_base_directory = project_path / fragment_directory
	else:
	fragment_directory = None

	_fragments, fragment_filenames = find_fragments(
	base_directory=str(fragment_base_directory),
	fragment_directory=fragment_directory,
	definitions=towncrier_config['types'],
	sections=towncrier_config['sections'],