docs: add release notes to website, create custom changelog template

.github/workflows/ci-cd.yml

@@ -33,7 +33,7 @@ jobs:
             mkdocs-material-
 
       - name: Install packages for documentation
-        run: pip install mkdocs-material mkdocstrings-python mkdocs-git-revision-date-localized-plugin mkdocs-glightbox black
+        run: pip install mkdocs-material mkdocstrings-python mkdocs-git-revision-date-localized-plugin mkdocs-glightbox black mkdocs-include-markdown-plugin
 
       - name: Build documentation
         run: mkdocs gh-deploy --force --config-file ./docs/mkdocs.yml

CHANGELOG.md

@@ -1,5 +1,6 @@
 # CHANGELOG
 
+<!--start-docs-->
 
 ## v0.2.1 (2024-10-21)
 

docs/docs/about/index.md

@@ -3,7 +3,6 @@ hide:
   - feedback
 ---
 
-
 # About
 
 Ozzy was initially developed by [Mariana Moreira](https://www.linkedin.com/in/mariana-t-moreira/) as a way to cope with her feeling of overwhelm when trying to process data from different simulation codes and designing complex analysis scripts for multidimensional data. Less of our time as physicists should be spent figuring out how to parse data into a convenient format and debugging the array manipulation bits of our code.

docs/docs/about/license.md

@@ -3,10 +3,11 @@ Copyright © 2024 Mariana Moreira - All Rights Reserved
 
 You may use, distribute and modify this code under the terms of the MIT License.
 
-???+ abstract "Full license text"
-    ``` {.yaml .no-copy}
-    --8<-- "LICENSE"
-    ```
+??? abstract "Full license text"
+
+    {%
+    include-markdown "./../../../LICENSE"
+    %}
 
 ## Bundled software components
 

docs/docs/about/release-notes.md

@@ -0,0 +1,7 @@
+# Release Notes
+
+{%
+    include-markdown "./../../../CHANGELOG.md"
+    start="<!--start-docs-->"
+%}
+

docs/mkdocs.yml

@@ -152,6 +152,17 @@ plugins:
       enable_creation_date: true
       fallback_to_build_date: true
   - glightbox
+  - include-markdown:
+      encoding: ascii
+      preserve_includer_indent: true
+      dedent: false
+      trailing_newlines: true
+      comments: true
+      rewrite_relative_urls: true
+      heading_offset: 0
+      start: <!--start-->
+      end: <!--end-->
+      recursive: true
 
 extra_javascript:
   - javascripts/mathjax.js
@@ -200,6 +211,7 @@ nav:
   - About: 
       - about/index.md
       - License: about/license.md
+      - Release Notes: about/release-notes.md
 
 
 

pyproject.toml

@@ -55,6 +55,7 @@ seaborn = "^0.13.2"
 ipython = "^8.28.0"
 ipykernel = "^6.29.5"
 
+
 [tool.poetry.group.optimize.dependencies]
 numpy-groupies = "^0.11.2"
 numbagg = "^0.8.2"
@@ -69,6 +70,7 @@ mkdocstrings-python = "^1.12.2"
 mkdocs-git-revision-date-localized-plugin = "^1.2.9"
 mkdocs-glightbox = "^0.4.0"
 black = "^24.10.0"
+mkdocs-include-markdown-plugin = "^7.0.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.3"
@@ -110,7 +112,7 @@ prerelease = false
 [tool.semantic_release.changelog]
 template_dir = "templates"
 changelog_file = "CHANGELOG.md"
-exclude_commit_patterns = []
+exclude_commit_patterns = ["test", "style", "chore"]
 
 [tool.semantic_release.changelog.environment]
 block_start_string = "{%"
@@ -131,7 +133,7 @@ env = "GIT_COMMIT_AUTHOR"
 default = "semantic-release <semantic-release>"
 
 [tool.semantic_release.commit_parser_options]
-allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "style", "refactor", "test"]
+allowed_tags = ["chore", "docs", "feat", "fix", "perf", "style", "refactor", "test"]
 minor_tags = ["feat"]
 patch_tags = ["fix", "perf"]
 default_bump_level = 0

templates/.changelog_header.md.j2

@@ -0,0 +1,11 @@
+# CHANGELOG
+
+<!--start-docs-->
+
+{%    if ctx.changelog_mode == "update"
+%}{#  # IMPORTANT: add insertion flag for next version update
+#}{{
+        insertion_flag ~ "\n"
+
+}}{%  endif
+%}

templates/.changelog_init.md.j2

@@ -0,0 +1,22 @@
+{#
+This changelog template initializes a full changelog for the project,
+it follows the following logic:
+  1. Header
+  2. Any Unreleased Details (uncommon)
+  3. all previous releases
+
+#}{#
+   #    Header
+#}{%    include ".changelog_header.md.j2"
+-%}{#
+   #    Any Unreleased Details (uncommon)
+#}{%    include ".unreleased_changes.md.j2"
+-%}{#
+    #   Since this is initialization, we are generating all the previous
+    #   release notes per version.
+#}{%    for release in context.history.released.values()
+%}{{      "\n"
+}}{%      include ".versioned_changes.md.j2"
+-%}{{     "\n"
+}}{%    endfor
+%}

templates/.changes.md.j2

@@ -0,0 +1,16 @@
+{#
+#}{%  for type_, commits in commit_objects
+%}{{
+        "\n### %s\n" | format(type_ | title)
+
+}}{%    for commit in commits
+%}{{
+          "\n* %s ([`%s`](%s))\n" | format(
+              commit.message.rstrip(),
+              commit.short_hash,
+              commit.hexsha | commit_hash_url,
+          )
+
+}}{%    endfor
+%}{%  endfor
+%}

templates/.unreleased_changes.md.j2

@@ -0,0 +1,7 @@
+{%    if unreleased_commits | length > 0
+%}{{    "\n## Unreleased\n"
+}}{%    set commit_objects = unreleased_commits
+%}{%    include ".changes.md.j2"
+-%}{{   "\n"
+}}{%  endif
+%}

templates/.versioned_changes.md.j2

@@ -0,0 +1,14 @@
+{#
+
+## **vX.X.X** (YYYY-MMM-DD)
+
+#}{{
+
+      "## %s (%s)\n" | format(
+        release.version.as_semver_tag(),
+        release.tagged_date.strftime("%Y-%m-%d")
+      )
+
+}}{%  set commit_objects = release["elements"] | dictsort
+%}{%  include ".changes.md.j2"
+-%}

templates/CHANGELOG.md.j2

@@ -0,0 +1,24 @@
+{#
+    This changelog template controls which changelog creation occurs
+    based on which mode is provided.
+
+    Modes:
+        - init: Initialize a full changelog from scratch
+        - update: Insert new version details where the placeholder exists in the current changelog
+
+#}{%  set insertion_flag = ctx.changelog_insertion_flag
+%}{%  set unreleased_commits = ctx.history.unreleased | dictsort
+%}{#
+#}{%  if ctx.changelog_mode == "init"
+%}{%    include ".changelog_init.md.j2"
+%}{#
+#}{%  elif ctx.changelog_mode == "update"
+%}{%    set prev_changelog_file = ctx.prev_changelog_file
+%}{%    set new_releases = []
+%}{%    if ctx.history.released.values() | length > 0
+%}{%      set new_releases = [ctx.history.released.values() | first]
+%}{%    endif
+%}{%    include ".changelog_update.md.j2"
+%}{#
+#}{%  endif
+%}