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 `news.rst` document right above the older
changelog entries using `towncrier-draft-entries` directive.

Co-Authored-By: Pradyun Gedam <[email protected]>

Author: webknjaz

docs/html/conf.py

@@ -13,6 +13,7 @@
 
 import glob
 import os
+import pathlib
 import re
 import sys
 
@@ -36,6 +37,7 @@
     'sphinx.ext.intersphinx',
     # third-party:
     'sphinx_inline_tabs',
+    'sphinxcontrib.towncrier',
     # in-tree:
     'docs_feedback_sphinxext',
     'pip_sphinxext',
@@ -316,3 +318,10 @@ def to_document_name(path, base_dir):
     'What content was useful?',
     'What content was not useful?',
 )
+
+# -- Options for towncrier_draft extension -----------------------------------
+
+towncrier_draft_autoversion_mode = 'draft'  # or: 'sphinx-release', 'sphinx-version'
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = pathlib.Path(docs_dir).parent
+# Not yet supported: towncrier_draft_config_path = 'pyproject.toml'  # relative to cwd

docs/html/news.rst

@@ -7,4 +7,6 @@ Changelog
     Major and minor releases of pip also include changes listed within
     prior beta releases.
 
+.. towncrier-draft-entries:: |release|, unreleased as on
+
 .. include:: ../../NEWS.rst

news/9172.doc.rst

@@ -0,0 +1 @@
+Render the unreleased pip version change notes on the news page in docs.

tools/requirements/docs.txt

@@ -1,6 +1,7 @@
 sphinx == 3.2.1
 furo
 sphinx-inline-tabs
+sphinxcontrib-towncrier
 
 # `docs.pipext` uses pip's internals to generate documentation. So, we install
 # the current directory to make it work.