1 files changed, 40 insertions, 36 deletions
diff --git a/tools/news/template.rst b/tools/news/template.rst
index 91003f202..8d0ceb89f 100644
--- a/tools/news/template.rst
+++ b/tools/news/template.rst
@@ -1,41 +1,45 @@
-{% set underline = "=" %}
-
-{{ underline * ((top_line)|length) }}
-{% for section in sections %}
-{% set underline = "-" %}
-{% if section %}
-{{ section }}
-{{ underline * section|length }}{% set underline = "~" %}
-
-{% endif %}
-{% if sections[section] %}
-{% for category, val in definitions.items() if category in sections[section] and category != 'trivial' %}
-
-{{ definitions[category]['name'] }}
-{{ underline * definitions[category]['name']|length }}
-
-{% if definitions[category]['showcontent'] %}
-{% for text, values in sections[section][category]|dictsort(by='value') %}
-- {{ text }}{% if category != 'vendor' and category != 'process' %} ({{ values|sort|join(', ') }}){% endif %}
-
+{# This is a heavily customised version of towncrier's default template. #}
+
+{#-
+  Only render if there's any changes to show.
+
+  This serves as a compatibility "hack" since we render unreleased news entries
+  in our changelog with ``sphinxcontrib.towncrier``; which triggers a render even
+  when there's no entries to be rendered.
+#}
+{% if sections[''] %}
+
+{#- Heading for individual version #}
+{{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 3) }}
+{#
+
+  The following loop will run exactly once, with ``section_name == ""``.
+
+  This is due to the undocumented "sections" feature in towncrier.
+  See https://github.com/twisted/towncrier/issues/61.
+
+  We don't use this feature, and this template doesn't render the section
+  heading for that reason.
+#}
+{% for section_name, entries_by_type in sections.items() -%}
+{# Only show types with entries and ``showcontent = true``, using the order from pyproject.toml #}
+{% for type_ in definitions if (sections[section_name][type_] and definitions[type_]['showcontent']) %}
+
+{# Heading for individual types #}
+{{ definitions[type_]['name'] }}
+{{ underlines[0] * definitions[type_]['name']|length }}
+{# This is the loop that generates individual entries #}
+{% for message, issue_reference in sections[section_name][type_]|dictsort(by='value') %}
+
+- {{ message }}
+  {%- if type_ not in ["vendor", "process"] %} ({{ issue_reference|sort|join(', ') }}){% endif %}
 {% endfor %}
-{% else %}
-- {{ sections[section][category]['']|sort|join(', ') }}
-
-
-{% endif %}
-{% if sections[section][category]|length == 0 %}
 
-No significant changes.
-
-
-{% else %}
-{% endif %}
-{% endfor %}
 {% else %}
-
+{# We only have entries where the type has ``showcontent = true``. #}
 No significant changes.
 
-
-{% endif %}
-{% endfor %}
+{% endfor -%}
+{% endfor -%}
+{% endif -%}