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]>
pypa · Dec 10, 2020 · 0ddfe08 · 0ddfe08
1 parent 27d8687
commit 0ddfe08
Show file tree

Hide file tree

Showing 4 changed files with 13 additions and 0 deletions.
diff --git a/docs/html/conf.py b/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
diff --git a/docs/html/news.rst b/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
diff --git a/news/9172.doc.rst b/news/9172.doc.rst
@@ -0,0 +1 @@
+Render the unreleased pip version change notes on the news page in docs.
diff --git a/tools/requirements/docs.txt b/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.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Render the unreleased pip version change notes on the news page in docs.