#706 Refactor markdown template to make it easier to read (#709)

Author: adiroiban

.gitattributes

@@ -0,0 +1,4 @@
+# Hint Github.com about the language use in our template files.
+# The project templates indicate the target output type (.md/.rst) rather than the template type (jinja)
+# Reference: https://github.com/github-linguist/linguist/blob/main/docs/overrides.md#using-gitattributes
+src/towncrier/templates/* linguist-language=Jinja

pyproject.toml

@@ -160,7 +160,7 @@ source = ["src", ".nox/tests-*/**/site-packages"]
 
 [tool.coverage.report]
 show_missing = true
-skip_covered = true
+skip_covered = false
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",

src/towncrier/newsfragments/706.doc

@@ -0,0 +1 @@
+Refactor the default markdown template to make it easier to understand, extend, and customize.

src/towncrier/templates/default.md

@@ -1,58 +1,116 @@
-{% if render_title %}
-{% if versiondata.name %}
-{{header_prefix}} {{ versiondata.name }} {{ versiondata.version }} ({{ versiondata.date }})
-{% else %}
-{{header_prefix}} {{ versiondata.version }} ({{ versiondata.date }})
-{% endif %}
-{% endif %}
-{% for section, _ in sections.items() %}
-{% if section %}
-
-{{header_prefix}}# {{section}}
-{% endif %}
-
-{% if sections[section] %}
-{% for category, val in definitions.items() if category in sections[section] %}
-{{header_prefix}}#{% if section %}#{% endif %} {{ definitions[category]['name'] }}
-
-{% for text, values in sections[section][category].items() %}
-- {{ text }}
-{%- if values %}
-{% if "\n  - " in text or '\n  * ' in text %}
-
-
-  (
-{%- else %}
-{% if text %} ({% endif %}
-{%- endif -%}
-{%- for issue in values %}
-{{ issue.split(": ", 1)[0] }}{% if not loop.last %}, {% endif %}
-{%- endfor %}
-{% if text %}){% endif %}
+{#-
+══════════════════════════════════════════════════════════════════════════════
+TOWNCRIER MARKDOWN TEMPLATE
+══════════════════════════════════════════════════════════════════════════════
+
+─── Macro: heading ─────────────────────────────────────────────────────────
+Purpose:
+   Generates Markdown headings with the appropriate number of # characters.
+   Based on header_prefix (default: "#") and the level argument.
+
+Arguments:
+   level             The relative heading level (1=#, 2=##, 3=###, etc.)
+-#}
+{%- macro heading(level) -%}
+    {{- "#" * ( header_prefix | length + level -1 ) }}
+{%- endmacro -%}
+
+{#-
+─── Variable: newline ──────────────────────────────────────────────────────
+Purpose:
+    Consistent newline handling. -#}
+{%- set newline = "\n" -%}
+
+{#- ════════════════════════ TEMPLATE GENERATION ════════════════════════ -#}
+{#- ─── TITLE HEADING ─── #}
+{#- render_title is false when title_format is specified in the config #}
+{%- if render_title %}
+    {%- if versiondata.name %}
+        {{- heading(1) ~ " " ~ versiondata.name ~ " " ~ versiondata.version ~ " (" ~ versiondata.date ~ ")" ~ newline }}
+    {%- else %}
+        {{- heading(1) ~ " " ~ versiondata.version ~ " (" ~ versiondata.date ~ ")" ~ newline }}
+    {%- endif %}
+{%- endif %}
+{#- If title_format is specified, we start with a new line #}
+{{- newline }}
+
+{%- for section, _ in sections.items() %}
+    {#- ─── SECTION HEADING ─── #}
+    {%- if section %}
+        {{- newline }}
+        {{- heading(2) ~ " " ~ section ~ newline }}
+        {{- newline }}
+    {%- endif %}
 
-{% else %}
+    {%- if sections[section] %}
 
-{% endif %}
-{% endfor %}
+        {%- for category, val in definitions.items() if category in sections[section] %}
+            {%- set issue_pks = [] %}
+            {#- ─── CATEGORY HEADING ─── #}
+            {#- Increase heading level if section is not present #}
+            {{- heading(3 if section else 2) ~" " ~ definitions[category]['name'] ~ newline }}
+            {{- newline }}
 
-{% if issues_by_category[section][category] and "]: " in issues_by_category[section][category][0] %}
-{% for issue in issues_by_category[section][category] %}
-{{ issue }}
-{% endfor %}
+            {#- ─── RENDER ENTRIES ─── #}
+            {%- for text, values in sections[section][category].items() %}
+                {#- Prepare the string of issue numbers (e.g., "#1, #9, #142") #}
+                {%- set issue_pks = [] %}
+                {%- for v_issue in values %}
+                    {%- set _= issue_pks.append(v_issue.split(": ", 1)[0]) %}
+                {%- endfor %}
+                {%- set issues_list = issue_pks | join(", ") %}
 
-{% endif %}
-{% if sections[section][category]|length == 0 %}
-No significant changes.
+                {#- Check if text contains a sublist #}
+                {%- set text_has_sublist = (("\n  - " in text) or ("\n  * " in text)) %}
 
-{% else %}
-{% endif %}
-{% endfor %}
-{% else %}
-No significant changes.
+                {#- CASE 1: No text, only issues #}
+                {#- Output: -  #1, #9, #142 #}
+                {%- if not text and issues_list %}
+                    {{- "- " ~ issues_list ~ newline }}
 
-{% endif %}
-{% endfor +%}
-{#
-This comment adds one more newline at the end of the rendered newsfile content.
+                {#- Cases where both text and issues exist #}
+                {%- elif text and issues_list %}
+                    {%- if text_has_sublist %}
+                        {#- CASE 3: Text with sublist #}
+                        {#- Output: - TEXT\n\n  (#1, #9, #142) #}
+                        {{- "- " ~ text ~ newline ~ newline ~ "  (" ~ issues_list ~ ")" ~ newline }}
+                    {%- else %}
+                        {#- CASE 2: Text, no sublist #}
+                        {#- Output: - TEXT (#1, #9, #142) #}
+                        {{- "- " ~ text ~ " (" ~ issues_list ~ ")" ~ newline }}
+                    {%- endif %}
+
+                {%- elif text %}
+                    {#- Implicit Case: Text, but no issues #}
+                    {#- Output: - TEXT #}
+                    {{- "- " ~ text ~ newline }}
+                {%- endif %}
+            {%- endfor %}
+
+            {#- New line between list and link references #}
+            {{- newline }}
+
+            {#- Link references #}
+            {%- if issues_by_category[section][category] and "]: " in issues_by_category[section][category][0] %}
+                {%- for issue in issues_by_category[section][category] %}
+                    {{- issue ~ newline }}
+                {%- endfor %}
+                {{- newline }}
+            {%- endif %}
+
+            {#- No changes in this category #}
+            {%- if sections[section][category]|length == 0 %}
+                {{- newline }}
+                {{- "No significant changes." ~ newline * 2 }}
+            {%- endif %}
+        {%- endfor %}
+    {%- else %}
+        {#- No changes in this section #}
+        {{- "No significant changes." ~ newline * 2 }}
+    {%- endif %}
+{%- endfor %}
+{#-
+Newline at the end of the rendered newsfile content.
 In this way the there are 2 newlines between the latest release and the previous release content.
-#}
+-#}
+{{- newline -}}

src/towncrier/test/test_build.py

@@ -1135,7 +1135,9 @@ def test_markdown_injected_after_header(self, runner):
             dedent=True,
         )
 
-        result = runner.invoke(_main, ["--date", "01-01-2001"], catch_exceptions=False)
+        result = runner.invoke(
+            _main, ["--date", "01-01-2001", "--yes"], catch_exceptions=False
+        )
 
         with open("foo/newsfragments/123.feature", "w") as f:
             f.write("Adds levitation")
@@ -1311,7 +1313,9 @@ def test_default_start_string(self, runner):
             dedent=True,
         )
 
-        result = runner.invoke(_main, ["--date", "01-01-2001"], catch_exceptions=False)
+        result = runner.invoke(
+            _main, ["--date", "01-01-2001", "--yes"], catch_exceptions=False
+        )
         self.assertEqual(0, result.exit_code, result.output)
         output = read("NEWS.rst")
 
@@ -1365,7 +1369,9 @@ def test_default_start_string_markdown(self, runner):
             dedent=True,
         )
 
-        result = runner.invoke(_main, ["--date", "01-01-2001"], catch_exceptions=False)
+        result = runner.invoke(
+            _main, ["--date", "01-01-2001", "--yes"], catch_exceptions=False
+        )
         self.assertEqual(0, result.exit_code, result.output)
         output = read("NEWS.md")
 
@@ -1417,7 +1423,9 @@ def test_markdown_no_name_title(self, runner):
             dedent=True,
         )
 
-        result = runner.invoke(_main, ["--date", "01-01-2001"], catch_exceptions=False)
+        result = runner.invoke(
+            _main, ["--date", "01-01-2001", "--yes"], catch_exceptions=False
+        )
         self.assertEqual(0, result.exit_code, result.output)
         output = read("NEWS.md")
 
@@ -1781,7 +1789,9 @@ def test_showcontent_default_toml_array(self, runner):
         a missing `showcontent` defaults to `true`.
         """
         write("foo/newsfragments/+new_feature.feature.md", "An exciting new feature!")
-        result = runner.invoke(_main, ["--date", "01-01-2001", "--version", "1.0.0"])
+        result = runner.invoke(
+            _main, ["--date", "01-01-2001", "--version", "1.0.0", "--yes"]
+        )
         news = read("NEWS.rst")
         expected = textwrap.dedent(
             """\
@@ -1821,7 +1831,9 @@ def test_directory_default_toml_array(self, runner):
         """
         write("foo/newsfragments/+new_feature.feature.md", "An exciting new feature!")
         write("foo/newsfragments/+bump_deps.deps.md", "We bumped our dependencies.")
-        result = runner.invoke(_main, ["--date", "01-01-2001", "--version", "1.0.0"])
+        result = runner.invoke(
+            _main, ["--date", "01-01-2001", "--version", "1.0.0", "--yes"]
+        )
         news = read("NEWS.rst")
         expected = textwrap.dedent(
             """\

src/towncrier/test/test_check.py

@@ -287,7 +287,12 @@ def test_none_stdout_encoding_works(self):
         """
         No failure when output is piped causing None encoding for stdout.
         """
-        runner = CliRunner()
+        try:
+            runner = CliRunner(mix_stderr=False)
+        except TypeError:
+            # Fallback for older Click versions (or unexpected signature)
+            print("TypeError with mix_stderr=False, falling back to echo_stdin=True")
+            runner = CliRunner(echo_stdin=True)
 
         with runner.isolated_filesystem():
             create_project("pyproject.toml", main_branch="master")
@@ -299,7 +304,6 @@ def test_none_stdout_encoding_works(self):
             check_call(["git", "add", fragment_path])
             check_call(["git", "commit", "-m", "add a newsfragment"])
 
-            runner = CliRunner(mix_stderr=False)
             result = runner.invoke(towncrier_check, ["--compare-with", "master"])
 
         self.assertEqual(0, result.exit_code)