Display changelog for unreleased version in docs

Author: webknjaz

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

docs/history.rst

@@ -5,6 +5,8 @@
 History
 *******
 
+.. towncrier-draft-entries:: |release|, unreleased as on |today|
+
 .. include:: ../CHANGES (links).rst
 
 Credits

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

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'

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