Migrate auto-generated docs code to docs_update.py

Author: kdeldycke

.github/workflows/autofix.yaml

@@ -1,45 +1,14 @@
 ---
-name: Autofix
+name: 🪄 Autofix
 "on":
+  workflow_dispatch:
   push:
-    # Only targets main branch to avoid amplification effects of auto-fixing
-    # the exact same stuff in multiple non-rebased branches.
     branches:
       - main
 
 jobs:
 
-  update-readme:
-    name: Update readme
-    runs-on: ubuntu-slim
-    steps:
-      - uses: actions/checkout@v6.0.2
-      - uses: astral-sh/setup-uv@v7.2.0
-      - name: Update readme
-        run: >
-          uv --no-progress run --frozen --
-          python -c 'from meta_package_manager.inventory import update_readme; update_readme()'
-      - uses: peter-evans/create-pull-request@v8.1.0
-        with:
-          assignees: ${{ github.actor }}
-          commit-message: "[autofix] Update readme"
-          title: "[autofix] Update readme"
-          body: >
-            <details><summary><code>Workflow metadata</code></summary>
-
-
-            > [Auto-generated on run `#${{ github.run_id }}`](${{ github.event.repository.html_url }}/actions/runs/${{
-            github.run_id }}) by `${{ github.job }}` job from [`docs.yaml`](${{ github.event.repository.html_url
-            }}/blob/${{ github.sha }}/.github/workflows/labels.yaml) workflow.
-
-
-            </details>
-          labels: "📚 documentation"
-          branch: update-readme
-          add-paths: |
-            readme.md
-
   autofix:
-    uses: kdeldycke/workflows/.github/workflows/autofix.yaml@v4.25.5
-    # Depends on the previous job so that the Markdown syntax auto-fixer can have an effect on auto-updated content.
-    needs: update-readme
+    uses: kdeldycke/repomatic/.github/workflows/autofix.yaml@v6.5.0
+    secrets:
+      WORKFLOW_UPDATE_GITHUB_PAT: ${{ secrets.WORKFLOW_UPDATE_GITHUB_PAT }}

docs/docs_update.py

@@ -0,0 +1,179 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+"""Dynamic documentation content generation.
+
+Called by repomatic's ``update-docs`` job to regenerate tables, diagrams and
+other dynamic content in ``readme.md``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from textwrap import dedent
+
+from click_extra.table import TableFormat, render_table
+from extra_platforms import Group, extract_members
+
+from meta_package_manager.base import Operations
+from meta_package_manager.inventory import MAIN_PLATFORMS
+from meta_package_manager.pool import pool
+
+
+def managers_sankey() -> str:
+    """Produce a sankey diagram to map ``mpm`` to all its supported managers."""
+    table = []
+    for mid, m in sorted(pool.items()):
+        line = f"Meta Package Manager,{mid},1"
+        table.append(line)
+
+    output = dedent("""\
+        ```mermaid
+        ---
+        config: {"sankey": {"showValues": false, "width": 800, "height": 400}}
+        ---
+        sankey-beta\n
+        """)
+    output += "\n".join(table)
+    output += "\n```"
+    return output
+
+
+def operation_matrix() -> tuple[str, str]:
+    """Produce a table of managers' metadata and supported operations."""
+    # Build up the column titles.
+    headers = [
+        "Package manager",
+        "Min. version",
+    ]
+
+    # Footnotes are used to details the OSes covered by each platform group.
+    footnotes = []
+
+    for p_obj in MAIN_PLATFORMS:
+        header_title = p_obj.name
+        # Add footnote for groups with more than one platform.
+        if isinstance(p_obj, Group) and len(p_obj) > 1:
+            footnote_tag = f"[^{p_obj.id}]"
+            header_title += footnote_tag
+            platforms_string = ", ".join(
+                sorted(
+                    (
+                        p.name
+                        for p in p_obj.members.values()  # type: ignore[attr-defined]
+                    ),
+                    key=str.casefold,
+                ),
+            )
+            footnotes.append(f"{footnote_tag}: {p_obj.name}: {platforms_string}.")
+        headers.append(header_title)
+
+    headers.extend(f"`{op.name}`" for op in Operations)
+
+    table = []
+    for mid, m in sorted(pool.items()):
+        line = [
+            f"[`{mid}`]({m.homepage_url})"
+            + ("" if not m.deprecated else f" [⚠️]({m.deprecation_url})"),
+            f"{m.requirement}",
+        ]
+        for p_obj in MAIN_PLATFORMS:
+            line.append(
+                p_obj.icon if m.platforms.issuperset(extract_members(p_obj)) else ""
+            )
+        for op in Operations:
+            line.append("✓" if m.implements(op) else "")
+        table.append(line)
+
+    # Set each column alignment.
+    alignments = ["left", "left"]
+    alignments.extend(["center"] * len(MAIN_PLATFORMS))
+    alignments.extend(["center"] * len(Operations))
+
+    rendered_table = render_table(
+        table,
+        headers=headers,
+        table_format=TableFormat.GITHUB,
+        colalign=alignments,
+        disable_numparse=True,
+    )
+
+    return rendered_table, "\n\n".join(footnotes)
+
+
+def replace_content(
+    filepath: Path,
+    new_content: str,
+    start_tag: str,
+    end_tag: str | None = None,
+) -> None:
+    """Replace in a file the content surrounded by the provided start and end tags.
+
+    If no end tag is provided, the whole content found after the start tag will be
+    replaced.
+    """
+    filepath = filepath.resolve()
+    assert filepath.exists(), f"File {filepath} does not exist."
+    assert filepath.is_file(), f"File {filepath} is not a file."
+
+    orig_content = filepath.read_text()
+
+    assert start_tag, "Start tag must be empty."
+    assert start_tag in orig_content, f"Start tag {start_tag!r} not found in content."
+    pre_content, table_start = orig_content.split(start_tag, 1)
+
+    if end_tag:
+        _, post_content = table_start.split(end_tag, 1)
+    else:
+        end_tag = ""
+        post_content = ""
+
+    filepath.write_text(
+        f"{pre_content}{start_tag}{new_content}{end_tag}{post_content}",
+    )
+
+
+def update_readme() -> None:
+    """Update ``readme.md`` with implementation table for each manager we support."""
+    readme = Path(__file__).parent.parent.joinpath("readme.md")
+
+    replace_content(
+        readme,
+        managers_sankey(),
+        "<!-- managers-sankey-start -->\n\n",
+        "\n\n<!-- managers-sankey-end -->",
+    )
+
+    matrix, footnotes = operation_matrix()
+    replace_content(
+        readme,
+        matrix,
+        "<!-- operation-matrix-start -->\n\n",
+        "\n\n<!-- operation-matrix-end -->",
+    )
+    replace_content(
+        readme,
+        footnotes,
+        "<!-- operation-footnotes-start -->\n\n",
+        # mdformat-footnote is stripping all HTML comments after footnotes:
+        # https://github.com/executablebooks/mdformat-footnote/issues/11
+        # So we protect the content to be replaced with an end tag that we put at the
+        # tail of the last footnote line, without any carriage return.
+        "<!-- operation-footnotes-end -->\n",
+    )
+
+
+if __name__ == "__main__":
+    update_readme()