From 0ddfe0882862717c24a32695ed5af5b69094226b Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sun, 29 Nov 2020 13:18:33 +0100 Subject: [PATCH] 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 --- docs/html/conf.py | 9 +++++++++ docs/html/news.rst | 2 ++ news/9172.doc.rst | 1 + tools/requirements/docs.txt | 1 + 4 files changed, 13 insertions(+) create mode 100644 news/9172.doc.rst diff --git a/docs/html/conf.py b/docs/html/conf.py index 7983187e9..b61c08bd5 100644 --- 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 @@ extensions = [ 'sphinx.ext.intersphinx', # third-party: 'sphinx_inline_tabs', + 'sphinxcontrib.towncrier', # in-tree: 'docs_feedback_sphinxext', 'pip_sphinxext', @@ -316,3 +318,10 @@ docs_feedback_questions_list = ( '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 index 137cddf36..8b54a02e6 100644 --- 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 new file mode 100644 index 000000000..fc0063766 --- /dev/null +++ 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 index 0c5103d0a..a5aae67c1 100644 --- 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.