docs: DOC-752 copies changelog on docs build and adds to sidebar menu (#1345)

Copies the changelog during sphinx build step into the docs for
publishing. Adds it to the sidebar. Downside of this approach is that
page 404s in local render, but this seems like the easiest way to
implement.

During this change I discovered our cog template wasn't actually being
used. The default template had some invalid JSX in the form of html
style="" spans around the word breaking. When I went to remove that I
discovered our template wasn't actually being used at all.

`cog bump --package` changelog uses the `package_template` which was
unset, so our template was never actually used. I made additional
changes to the template to correct whitespace in output, and add PR
links, and adjust the output heading.

Finally, I added a script that can regen the changelog, to back fix all
the old changelog entries.

Author: dsmmcken

cog.toml

@@ -49,21 +49,28 @@ ci = { changelog_title = "", omit_from_changelog = true }
 [changelog]
 path = "CHANGELOG.md"
 template = "deephaven-changelog-template"
+package_template = "deephaven-changelog-template"
 remote = "github.com"
 repository = "deephaven-plugins"
 owner = "deephaven"
+# `signature` must match `git log --format=%an` exactly. `username` is the
+# github handle, which is what `commit.author` resolves to in the changelog
+# template — that's what we render. Multiple entries per handle cover
+# historical git-author name variants (e.g. "Joe" vs "Joe Numainville").
 authors = [
     { username = "jnumainville", signature = "Joe Numainville" },
+    { username = "jnumainville", signature = "Joe" },
     { username = "mofojed", signature = "Mike Bender" },
+    { username = "mofojed", signature = "mikebender" },
     { username = "devinrsmith", signature = "Devin Smith" },
-    { username = "mattrunyon", signature = "Matt Runyon" },
+    { username = "mattrunyon", signature = "Matthew Runyon" },
     { username = "vbabich", signature = "Vlad Babich" },
+    { username = "dsmmcken", signature = "Don" },
     { username = "dsmmcken", signature = "Don McKenzie" },
     { username = "bmingles", signature = "Brian Ingles" },
     { username = "niloc132", signature = "Colin Alworth" },
     { username = "rachelmbrubaker", signature = "Rachel Brubaker" },
     { username = "JamesXNelson", signature = "James Nelson" },
-
 ]
 
 [bump_profiles]

deephaven-changelog-template

@@ -1,54 +1,51 @@
-{# Tera templates are used to generate the changelog content -#}
-{# https://keats.github.io/tera/docs/ -#}
-{# Based on Cocogittos remote template, but adds breaking changes: https://github.com/cocogitto/cocogitto/blob/main/src/conventional/changelog/template/remote -#}
-{# First display all the breaking changes -#}
-{% set breaking_commits = commits | filter(attribute="breaking_change", value=true) -%}
-{% if breaking_commits | length > 0 -%}
-#### ⚠ Breaking Changes
+{%- if version.tag %}
+## {{ version.tag }} - {{ date | date(format="%Y-%m-%d") }}
+{% else %}
+{%- set from = commits | last -%}
+{%- set to = version.id -%}
+{%- set from_shorthand = from.id | truncate(length=7, end="") -%}
+{%- set to_shorthand = to | truncate(length=7, end="") %}
+## Unreleased ({{ from_shorthand ~ ".." ~ to_shorthand }})
+{% endif -%}
+{%- set breaking_commits = commits | filter(attribute="breaking_change", value=true) -%}
+{%- if breaking_commits | length > 0 %}
+#### Breaking Changes
 
 {% for commit in breaking_commits -%}
-{% set commit_link = repository_url ~ "/commit/" ~ commit.id -%}
-{% set shorthand = commit.id | truncate(length=7, end="") -%}
-{% for footer in commit.footer | filter(attribute="token", value="BREAKING CHANGE") -%}
-- {{ footer.content }} - ([{{shorthand}}]({{ commit_link }}))
+{%- set parts = commit.summary | split(pat=" (#") -%}
+{%- if parts | length > 1 -%}
+{%- set pr_num = parts | last | replace(from=")", to="") -%}
+- {{ parts | first }} ([#{{ pr_num }}]({{ repository_url }}/pull/{{ pr_num }})) - ({{ commit.id | truncate(length=7, end="") }}) - {{ commit.author | default(value=commit.signature) }}
+{% else -%}
+- {{ commit.summary }} - ({{ commit.id | truncate(length=7, end="") }}) - {{ commit.author | default(value=commit.signature) }}
+{% endif -%}
 {% endfor -%}
-{% endfor -%}
-{% endif %}
-
-{# Now group the rest of the commits and display them -#}
-{% set typed_commit_map = commits | group_by(attribute="type") -%}
-{% set type_order = ["Features", "Bug Fixes", "Performance Improvements", "Miscellaneous Chores", "Documentation", "Refactoring", "Build system", "Style"] -%}
-{% for type in type_order -%}
-{% if typed_commit_map[type] -%}
+{%- endif -%}
+{%- set typed_commit_map = commits | group_by(attribute="type") -%}
+{%- set type_order = ["Features", "Bug Fixes", "Performance Improvements", "Miscellaneous Chores", "Documentation", "Refactoring", "Revert", "Tests", "Build system", "Style"] -%}
+{%- for type in type_order -%}
+{%- if typed_commit_map[type] %}
 #### {{ type | upper_first }}
-{% for scope, scoped_commits in typed_commit_map[type] | group_by(attribute="scope") -%}
 
+{% for scope, scoped_commits in typed_commit_map[type] | group_by(attribute="scope") -%}
 {% for commit in scoped_commits | sort(attribute="scope") -%}
-    {% if commit.author and repository_url -%}
-        {% set author = "@" ~ commit.author -%}
-        {% set author_link = platform ~ "/" ~ commit.author -%}
-        {% set author = "[" ~ author ~ "](" ~ author_link ~ ")" -%}
-    {% else -%}
-        {% set author = commit.signature -%}
-    {% endif -%}
-    {% set commit_link = repository_url ~ "/commit/" ~ commit.id -%}
-    {% set shorthand = commit.id | truncate(length=7, end="") -%}
-    - **({{ scope }})** {{ commit.summary }} - ([{{shorthand}}]({{ commit_link }})) - {{ author }}
+{%- set parts = commit.summary | split(pat=" (#") -%}
+{%- if parts | length > 1 -%}
+{%- set pr_num = parts | last | replace(from=")", to="") -%}
+- **({{ commit.scope }})** {{ parts | first }} ([#{{ pr_num }}]({{ repository_url }}/pull/{{ pr_num }})) - ({{ commit.id | truncate(length=7, end="") }}) - {{ commit.author | default(value=commit.signature) }}
+{% else -%}
+- **({{ commit.scope }})** {{ commit.summary }} - ({{ commit.id | truncate(length=7, end="") }}) - {{ commit.author | default(value=commit.signature) }}
+{% endif -%}
 {% endfor -%}
-
 {% endfor -%}
-
 {% for commit in typed_commit_map[type] | unscoped -%}
-    {% if commit.author and repository_url -%}
-        {% set author = "@" ~ commit.author -%}
-        {% set author_link = platform ~ "/" ~ commit.author -%}
-        {% set author = "[" ~ author ~ "](" ~ author_link ~ ")" -%}
-    {% else -%}
-        {% set author = commit.signature -%}
-    {% endif -%}
-    {% set commit_link = repository_url ~ "/commit/" ~ commit.id -%}
-    {% set shorthand = commit.id | truncate(length=7, end="") -%}
-    - {{ commit.summary }} - ([{{shorthand}}]({{ commit_link }})) - {{ author }}
+{%- set parts = commit.summary | split(pat=" (#") -%}
+{%- if parts | length > 1 -%}
+{%- set pr_num = parts | last | replace(from=")", to="") -%}
+- {{ parts | first }} ([#{{ pr_num }}]({{ repository_url }}/pull/{{ pr_num }})) - ({{ commit.id | truncate(length=7, end="") }}) - {{ commit.author | default(value=commit.signature) }}
+{% else -%}
+- {{ commit.summary }} - ({{ commit.id | truncate(length=7, end="") }}) - {{ commit.author | default(value=commit.signature) }}
+{% endif -%}
 {% endfor -%}
-{% endif %}
-{% endfor -%}
+{%- endif -%}
+{%- endfor -%}