💄📝 Integrate sphinxcontrib.towncrier @ docs

CHANGES.rst

@@ -1,7 +1,3 @@
-=========
-Changelog
-=========
-
 ..
     You should *NOT* be adding new change log entries to this file, this
     file is managed by towncrier. You *may* edit previous change logs to

CHANGES/891.bugfix.rst

@@ -1 +1,2 @@
-Updated type hints to include `URL.missing_port`, `URL.__bytes__` and the `encoding` argument to `URL.joinpath()`
+Updated type hints to include ``URL.missing_port()``, ``URL.__bytes__()`` and
+the ``encoding`` argument to :py:meth:`~yarl.URL.joinpath`.

docs/changes.rst

@@ -1,3 +1,15 @@
 .. _yarl_changes:
 
+=========
+Changelog
+=========
+
+To be included in v\ |release| (if present)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. towncrier-draft-entries:: |release| [UNRELEASED DRAFT]
+
+Released versions
+^^^^^^^^^^^^^^^^^
+
 .. include:: ../CHANGES.rst

docs/conf.py

@@ -26,10 +26,12 @@
 #
 # needs_sphinx = '1.0'
 
-import pathlib
 import re
+from pathlib import Path
 
-_docs_path = pathlib.Path(__file__).parent
+PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
+
+_docs_path = Path(__file__).parent
 _version_path = _docs_path / "../yarl/__init__.py"
 
 
@@ -59,6 +61,7 @@
     "sphinx.ext.viewcode",
     # Third-party extensions:
     "alabaster",
+    "sphinxcontrib.towncrier.ext",  # provides `towncrier-draft-entries` directive
 ]
 
 
@@ -427,3 +430,10 @@
 
 default_role = "any"
 nitpicky = True
+
+# -- Options for towncrier_draft extension -----------------------------------
+
+towncrier_draft_autoversion_mode = "draft"  # or: 'sphinx-version', 'sphinx-release'
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = PROJECT_ROOT_DIR
+# Not yet supported: towncrier_draft_config_path = 'pyproject.toml'  # relative to cwd

requirements/doc.txt

@@ -1 +1,2 @@
 sphinx==7.0.1
+sphinxcontrib-towncrier