Improve our towncrier template, to do the right thing after releases

This also adds a bunch of comments, which should serve as useful guides
to future humans that work on these files.

1 files changed, 33 insertions, 28 deletions

diff --git a/tools/news/template.rst b/tools/news/template.rst
index 91003f202..856b5610a 100644
--- a/tools/news/template.rst
+++ b/tools/news/template.rst
@@ -1,41 +1,46 @@
-{% set underline = "=" %}
+{# This is a heavily customised version of towncrier's default template. #}
 
-{{ underline * ((top_line)|length) }}
-{% for section in sections %}
-{% set underline = "-" %}
-{% if section %}
-{{ section }}
-{{ underline * section|length }}{% set underline = "~" %}
+{#-
+  Only render if there's any changes to show.
 
-{% endif %}
-{% if sections[section] %}
-{% for category, val in definitions.items() if category in sections[section] and category != 'trivial' %}
+  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[''] %}
 
-{{ definitions[category]['name'] }}
-{{ underline * definitions[category]['name']|length }}
+{#- Heading for individual version #}
+{{ versiondata.version }} ({{ versiondata.date }})
+{{ top_underline * ((versiondata.version + versiondata.date)|length + 3) }}
 
-{% 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 %}
+{#
 
-{% endfor %}
-{% else %}
-- {{ sections[section][category]['']|sort|join(', ') }}
+  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.
 
-{% endif %}
-{% if sections[section][category]|length == 0 %}
+  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']) %}
 
-No significant changes.
+{# Heading for individual types #}
+{{ definitions[type_]['name'] }}
+{{ underlines[0] * definitions[type_]['name']|length }}
 
-
-{% else %}
-{% endif %}
+{# 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 %}
 
+{% else %}
+{# We only have entries where the type has ``showcontent = true``. #}
 No significant changes.
 
-
-{% endif %}
-{% endfor %}
+{% endfor -%}
+{% endfor -%}
+{% endif -%}