From 36da400de17006eb3457b2b7c292c0c214a50994 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Wed, 21 Apr 2021 18:29:59 +0200
Subject: [PATCH] Display changelog for unreleased version in docs

---
 docs/conf.py     | 30 ++++++++++++++++++++++++++++++
 docs/history.rst |  2 ++
 pytest.ini       |  6 ++++++
 setup.cfg        |  2 ++
 tox.ini          |  2 +-
 5 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index d8996d9429e..58c3c00c241 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,3 +1,9 @@
+from functools import partial
+from pathlib import Path
+
+from setuptools_scm import get_version
+
+
 extensions = ['sphinx.ext.autodoc', 'jaraco.packaging.sphinx', 'rst.linker']
 
 master_doc = "index"
@@ -99,3 +105,27 @@
 
 # Add support for inline tabs
 extensions += ['sphinx_inline_tabs']
+
+# Add support for the unreleased "next-version" change notes
+extensions += ['sphinxcontrib.towncrier']
+
+
+# -- Options for towncrier_draft extension --------------------------------------------
+
+PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
+get_scm_version = partial(get_version, root=PROJECT_ROOT_DIR)
+
+# The short X.Y version
+version = '.'.join(
+    get_scm_version(
+        local_scheme='no-local-version',
+    ).split('.')[:3],
+)
+
+# The full version, including alpha/beta/rc tags
+release = get_scm_version()
+
+towncrier_draft_autoversion_mode = "draft"  # or: 'sphinx-release', 'sphinx-version'
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = PROJECT_ROOT_DIR
+# Not yet supported: towncrier_draft_config_path = 'pyproject.toml'  # relative to cwd
diff --git a/docs/history.rst b/docs/history.rst
index faf7adfe2c2..e13b38df0e0 100644
--- a/docs/history.rst
+++ b/docs/history.rst
@@ -5,6 +5,8 @@
 History
 *******
 
+.. towncrier-draft-entries:: |release|, unreleased as on |today|
+
 .. include:: ../CHANGES (links).rst
 
 Credits
diff --git a/pytest.ini b/pytest.ini
index 9aa1b17347d..7f68c21c133 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -21,3 +21,9 @@ filterwarnings=
     # https://github.com/pypa/setuptools/issues/2081
     ignore:lib2to3 package is deprecated:PendingDeprecationWarning
     ignore:lib2to3 package is deprecated:DeprecationWarning
+
+	# Having setuptools_scm in docs/conf.py causes this because pytest, besides
+	# running tests also runs linters. But since GitHub Actions CI/CD workflows
+	# do not perform full checkouts by default, the Git clone in that env is
+	# shallow:
+	ignore:"/home/runner/work/setuptools/setuptools" is shallow and may cause errors:UserWarning:setuptools_scm.git
diff --git a/setup.cfg b/setup.cfg
index ebdc2c638c8..eb3fa0d56cb 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -74,7 +74,9 @@ docs =
 
 	# local
 	pygments-github-lexers==0.0.5
+	setuptools-scm
 	sphinx-inline-tabs
+	sphinxcontrib-towncrier
 
 ssl =
 	wincertstore==0.2; sys_platform=='win32'
diff --git a/tox.ini b/tox.ini
index 04e77ed5273..2adecf2bdb8 100644
--- a/tox.ini
+++ b/tox.ini
@@ -6,7 +6,7 @@ tox_pip_extensions_ext_venv_update = true
 toxworkdir={env:TOX_WORK_DIR:.tox}
 
 [testenv]
-deps =
+deps = setuptools-scm
 commands =
 	pytest {posargs}
 usedevelop = True