Add a preview for the "next release" change notes (#1016)

* Add a preview for the "next release" change notes

This change integrates `sphinxcontrib-towncrier` into the docs build.
It uses Towncrier and its configs to render a draft changelog as RST
and injects that into the `changelog.rst` document right above the
older changelog entries using `towncrier-draft-entries` directive.

* Drop the change note from PR #1016

This partially reverts commit 0165dc355d2eb475cf59894d1561efb9b1963a39.

* Use `Not yet released` in the changelog draft

Co-authored-by: Hynek Schlawack <hs@ox.cx>

docs/changelog.rst

@@ -1 +1,7 @@
 .. include:: ../CHANGELOG.rst
+   :end-before: Changes for the upcoming release can be found
+
+.. towncrier-draft-entries:: Not yet released
+
+.. include:: ../CHANGELOG.rst
+   :start-after: .. towncrier release notes start

docs/conf.py

@@ -1,6 +1,12 @@
 # SPDX-License-Identifier: MIT
 
 from importlib import metadata
+from pathlib import Path
+
+
+# -- Path setup -----------------------------------------------------------
+
+PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
 
 
 # -- General configuration ------------------------------------------------
@@ -35,6 +41,7 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "notfound.extension",
+    "sphinxcontrib.towncrier",
 ]
 
 
@@ -153,3 +160,11 @@ intersphinx_mapping = {
 
 # Allow non-local URIs so we can have images in CHANGELOG etc.
 suppress_warnings = ["image.nonlocal_uri"]
+
+
+# -- Options for sphinxcontrib.towncrier extension ------------------------
+
+towncrier_draft_autoversion_mode = "draft"
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = PROJECT_ROOT_DIR
+towncrier_draft_config_path = "pyproject.toml"

setup.py

@@ -43,7 +43,13 @@ CLASSIFIERS = [
 ]
 INSTALL_REQUIRES = []
 EXTRAS_REQUIRE = {
-    "docs": ["furo", "sphinx", "zope.interface", "sphinx-notfound-page"],
+    "docs": [
+        "furo",
+        "sphinx",
+        "zope.interface",
+        "sphinx-notfound-page",
+        "sphinxcontrib-towncrier",
+    ],
     "tests-no-zope": [
         # For regression test to ensure cloudpickle compat doesn't break.
         'cloudpickle; python_implementation == "CPython"',