Show pending newsfragments in documentation previews

sphinxcontrib-towncrier renders the newsfragments that have not been
released yet at the top of the changelog, so that documentation
previews built from pull requests include their entries.

The title is now rendered by a custom towncrier template instead of
title_format, so that the draft gets a plain "Unreleased" heading
while releases keep their linked heading, unchanged.

Author: RazerM

docs/changelog.rst

@@ -1,6 +1,10 @@
 Change Log
 ==========
 
+.. towncrier-draft-entries::
+
+   Unreleased
+
 .. towncrier release notes start
 
 `2.0.0 <https://github.com/python-astrodynamics/spacetrack/releases/tag/2.0.0>`_ - 2026-08-10

docs/conf.py

@@ -7,6 +7,7 @@
 
 import re
 from importlib.metadata import distribution
+from pathlib import Path
 
 from parver import Version
 
@@ -44,8 +45,14 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.towncrier.ext",
 ]
 
+# Render pending newsfragments at the top of the changelog, so that previews
+# built from pull requests show their entries.
+towncrier_draft_include_empty = False
+towncrier_draft_working_directory = str(Path(__file__).resolve().parent.parent)
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.

newsfragments/template.rst.jinja

@@ -0,0 +1,39 @@
+{% if render_title %}
+{% if versiondata.version == "Unreleased" %}
+Unreleased
+{{ top_underline * 10 }}
+{% else %}
+{% set title = "`" ~ versiondata.version ~ " <https://github.com/python-astrodynamics/spacetrack/releases/tag/" ~ versiondata.version ~ ">`_ - " ~ versiondata.date %}
+{{ title }}
+{{ top_underline * title|length }}
+{% endif %}
+{% endif %}
+{% for section, _ in sections.items() %}
+{% set underline = underlines[0] %}{% if section %}{{section}}
+{{ underline * section|length }}{% set underline = underlines[1] %}
+
+{% endif %}
+
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section]%}
+{{ definitions[category]['name'] }}
+{{ underline * definitions[category]['name']|length }}
+
+{% for text, values in sections[section][category].items() %}
+- {% if text %}{{ text }}{% if values %} ({{ values|join(', ') }}){% endif %}{% else %}{{ values|join(', ') }}{% endif  %}
+
+{% endfor %}
+
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+
+{% else %}
+{% endif %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}
+{% endfor %}

pyproject.toml

@@ -58,6 +58,7 @@ docs = [
     "furo>=2024.8.6",
     "parver>=0.5",
     "sphinx>=7.4.7",
+    "sphinxcontrib-towncrier>=0.5.0a0",
 ]
 docstest = [
     { include-group = "docs" },
@@ -116,8 +117,9 @@ ignore = ["D001"]
 [tool.towncrier]
 directory = "newsfragments"
 filename = "docs/changelog.rst"
+template = "newsfragments/template.rst.jinja"
 issue_format = "`#{issue} <https://github.com/python-astrodynamics/spacetrack/issues/{issue}>`_"
-title_format = "`{version} <https://github.com/python-astrodynamics/spacetrack/releases/tag/{version}>`_ - {project_date}"
+title_format = ""
 underlines = ["-", "~"]
 
 [[tool.towncrier.type]]