Add Sankey diagram mapping platforms to groups

changelog.md

@@ -5,6 +5,8 @@
 > \[!IMPORTANT\]
 > This version is not released yet and is under active development.
 
+- Map all platforms to their groups with a Sankey diagram in documentation.
+
 ## [4.9.0 (2024-07-25)](https://github.com/kdeldycke/click-extra/compare/v4.8.3...v4.9.0)
 
 - Switch from Poetry to `uv`.

click_extra/docs_update.py

@@ -96,6 +96,22 @@ def generate_lexer_table() -> str:
     )
 
 
+def generate_platform_sankey() -> str:
+    """Produce a Sankey diagram to map all platforms to their platforms."""
+    table = []
+
+    # Display biggest groups first
+    for group in sorted(ALL_GROUPS, key=lambda g: len(g.platform_ids), reverse=True):
+        for platform in group.platforms:
+            line = f"{group.id},{platform.id},1"
+            table.append(line)
+
+    output = "```mermaid\nsankey-beta\n\n"
+    output += "\n".join(table)
+    output += "\n```"
+    return output
+
+
 def generate_platforms_graph(
     graph_id: str,
     description: str,
@@ -171,7 +187,14 @@ def update_docs() -> None:
     )
     assert frozenset(g for groups in all_groups for g in groups["groups"]) == ALL_GROUPS
 
-    # Update the platform diagram in Sphinx's documentation.
+    # Update the platform diagrams in Sphinx's documentation.
+    replace_content(
+        project_root.joinpath("docs/platforms.md"),
+        "<!-- platform-sankey-start -->\n\n",
+        "\n\n<!-- platform-sankey-end -->",
+        generate_platform_sankey(),
+    )
+
     platform_doc = project_root.joinpath("docs/platforms.md")
     for top_groups in all_groups:
         replace_content(

docs/conf.py

@@ -55,6 +55,9 @@
 ]
 myst_fence_as_directive = ["mermaid"]
 
+# Always use the latest version of Mermaid.
+mermaid_version = "latest"
+
 master_doc = "index"
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/platforms.md

@@ -1,5 +1,67 @@
 # Platform detection
 
+<!-- platform-sankey-start -->
+
+```mermaid
+sankey-beta
+
+all_platforms,aix,1
+all_platforms,cygwin,1
+all_platforms,freebsd,1
+all_platforms,hurd,1
+all_platforms,linux,1
+all_platforms,macos,1
+all_platforms,netbsd,1
+all_platforms,openbsd,1
+all_platforms,solaris,1
+all_platforms,sunos,1
+all_platforms,windows,1
+all_platforms,wsl1,1
+all_platforms,wsl2,1
+unix,aix,1
+unix,cygwin,1
+unix,freebsd,1
+unix,hurd,1
+unix,linux,1
+unix,macos,1
+unix,netbsd,1
+unix,openbsd,1
+unix,solaris,1
+unix,sunos,1
+unix,wsl1,1
+unix,wsl2,1
+unix_without_macos,aix,1
+unix_without_macos,cygwin,1
+unix_without_macos,freebsd,1
+unix_without_macos,hurd,1
+unix_without_macos,linux,1
+unix_without_macos,netbsd,1
+unix_without_macos,openbsd,1
+unix_without_macos,solaris,1
+unix_without_macos,sunos,1
+unix_without_macos,wsl1,1
+unix_without_macos,wsl2,1
+bsd,freebsd,1
+bsd,macos,1
+bsd,netbsd,1
+bsd,openbsd,1
+bsd,sunos,1
+bsd_without_macos,freebsd,1
+bsd_without_macos,netbsd,1
+bsd_without_macos,openbsd,1
+bsd_without_macos,sunos,1
+system_v,aix,1
+system_v,solaris,1
+linux_layers,wsl1,1
+linux_layers,wsl2,1
+unix_layers,cygwin,1
+other_unix,hurd,1
+all_windows,windows,1
+all_linux,linux,1
+```
+
+<!-- platform-sankey-end -->
+
 ## OS families
 
 All platforms are grouped in sets of non-overlpaping families: