📝 Integrate sphinxcontrib-towncrier

[webknjaz]

This plugin embeds displaying a changelog draft right into the Sphinx ecosystem, removing the need to separately run the towncrier --draft command externally.
It works with native Sphinx build runs universally, meaning that the result is the same and embedded for local runs, and is not only set up on RTD in a disconnected manner.

DISCLAIMER: I authored this Sphinx extension.

• Document your change, if it is a non-trivial one.
  • A maintainer might label the issue skip-news if the change does not need to be in the changelog.
  • Otherwise, create a news fragment with towncrier create <IssueNumber>.<type> which will be
    included in the changelog. <type> can be one of the types defined in ./towncrier.toml.
    If necessary you can write details or offer examples on how the new change is supposed to work.
  • Generating the doc is done with tox -e docs
• Relate your change to an issue in the tracker if such an issue exists (Refs incorrect analysing of etree #1234, Closes incorrect analysing of etree #1234)
• Write comprehensive commit messages and/or a good description of what the PR does.
• Keep the change small, separate the consensual changes from the opinionated one.
  Don't hesitate to open multiple PRs if the change requires it. If your review is so
  big it requires to actually plan and allocate time to review, it's more likely
  that it's going to go stale.
• If you used multiple emails or multiple names when contributing, add your mails
  and preferred name in script/.contributors_aliases.json

Type of Changes

	Type
✓	🔨 Refactoring
✓	📜 Docs

Description

I just saw the changelog draft hack and figured I'd try plugging in my thing. Evidently, the docs structure is a bit different compared to what I'm used to so I'm just experimenting with the integration for now and want to preview how it goes.
I wasn't sure about a change note. I can write it later if needed. Recently I started using more granular Towncrier fragments in my projects, introducing sections targeting the contributors and downstreams (e.g. https://docs.aiohttp.org/en/stable/changes.html#contributor-facing-changes). I'd use one of those if they existed, but since they don't, perhaps an internal note would fit. Let me know!

With the above in mind, I'm opening this PR in the draft status and may change it to review-ready later.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.81%. Comparing base (67bfab4) to head (7002cb7).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9569   +/-   ##
=======================================
  Coverage   95.81%   95.81%           
=======================================
  Files         173      173           
  Lines       18825    18825           
=======================================
  Hits        18038    18038           
  Misses        787      787           

[webknjaz]

The integration works but needs adjustments to look nicer: https://pylint--9569.org.readthedocs.build/en/9569/whatsnew/3/3.2/index.html#to-be-included-in-the-next-release vs. https://pylint.readthedocs.io/en/latest/whatsnew/3/3.2/index.html.

I'm undrafting the PR for visibility. Let me know if you'd like me to proceed with completing it beyond a simple demo state.

[DanielNoord]

@Pierre-Sassoulas What do you think about this? I like it but it indeed needs some polish.

[Pierre-Sassoulas]

I'm not sure we need this, there's a lot of complexity and options added to the sphinx conf. Also it would leave us open to more supply chains attacks.

[Pierre-Sassoulas]

Sorry @webknjaz, this look nice indeed and maybe we could add it someday when the project is more mature.

[webknjaz]

🤷‍♂️ well, it's quite mature. The only reason I'm not marking it as stable is that the test coverage needs to be improved. FWIW it's been powering such projects as pip, setuptools, attrs, aiohttp for 2-4 years. I'm just very nitpicky as to what I declare stable :)

P.S. Actually, some of the conf.py settings are redundant, as I said — it's an unpolished demo of what's possible.