docs: make the trophy case prettier (#279)

woodruffw · Dec 12, 2024 · 71619c4 · 71619c4
1 parent 7c71e81
commit 71619c4
Show file tree

Hide file tree

Showing 6 changed files with 364 additions and 49 deletions.
diff --git a/Makefile b/Makefile
@@ -11,5 +11,11 @@ site-live: site-requirements.txt
 	uvx --with-requirements $< mkdocs serve
 
 .PHONY: snippets
-snippets:
+snippets: trophies
 	cargo run -- -h > docs/snippets/help.txt
+
+.PHONY: trophies
+trophies: docs/snippets/trophies.md
+
+docs/snippets/trophies.md: docs/snippets/trophies.txt docs/snippets/render-trophies.py
+	uv run --no-project docs/snippets/render-trophies.py > $@
diff --git a/docs/development.md b/docs/development.md
@@ -167,6 +167,36 @@ INFO    -  [22:18:40] Browser connected: http://127.0.0.1:9999/zizmor/developmen
 
 Visit the listed URL to see your live changes.
 
+### Updating the snippets
+
+`zizmor`'s website contains various static snippets. To update these:
+
+```
+make snippets
+```
+
+Most of the time, this should result in no changes, since the snippets
+will already be up-to-date.
+
+### Updating the trophy case
+
+!!! tip
+
+    Additions to the trophy case are welcome, but we currently limit them
+    to repositories with 100 or more "stars" to keep things tractable.
+
+The [Trophy Case](./trophy-case.md) is kept up-to-date through the data in
+the `docs/snippets/trophies.txt` file.
+
+To add a new trophy to the trophy case, add it to that file *in the same
+format* as the other entries.
+
+Then, regenerate the trophy case:
+
+```
+make trophies
+```
+
 ## Adding or modifying an audit
 
 ### Before getting started
@@ -245,11 +275,7 @@ The general procedure for changing an existing audit is:
 
 `zizmor`'s documentation contains a copy of `zizmor --help`, which the CI
 checks to ensure that it remains updated. If you change `zizmor`'s CLI,
-you may need to regenerate the documentation snippets and check-in the results:
-
-```bash
-make snippets
-```
+you may need to [update the snippets](#updating-the-snippets).
 
 [clap]: https://docs.rs/clap/latest/clap/index.html
 

diff --git a/docs/snippets/render-trophies.py b/docs/snippets/render-trophies.py
@@ -0,0 +1,27 @@
+#!/usr/bin/env python
+
+# render-trophies: take trophies.txt and produce a pretty
+# mkdocs-material card grid list from it
+
+from pathlib import Path
+
+
+_TROPHIES = Path(__file__).parent / "trophies.txt"
+
+_TEMPLATE = """
+-   ![](https://github.com/{org}.png?size=40){{ width=\"40\" loading=lazy align=left }} {org}/{repo}
+
+    ---
+
+    {trophy}"""
+
+for trophy in sorted(_TROPHIES.open().readlines()):
+    trophy = trophy.strip()
+    if not trophy or trophy.startswith("#"):
+        continue
+
+    org, rest = trophy.split("/")
+    repo, _ = rest.split("#")
+    # NOTE: We request 40x40 from GitHub, but sometimes it gives us a bigger one.
+    # Consequently, we also style with `width` to keep things consistent.
+    print(_TEMPLATE.format(org=org, repo=repo, trophy=trophy))
diff --git a/docs/snippets/trophies.md b/docs/snippets/trophies.md
@@ -0,0 +1,246 @@
+
+-   ![](https://github.com/DataDog.png?size=40){ width="40" loading=lazy align=left } DataDog/datadog-agent
+
+    ---
+
+    DataDog/datadog-agent#30871
+
+-   ![](https://github.com/Diaoul.png?size=40){ width="40" loading=lazy align=left } Diaoul/subliminal
+
+    ---
+
+    Diaoul/subliminal#1190
+
+-   ![](https://github.com/Homebrew.png?size=40){ width="40" loading=lazy align=left } Homebrew/brew
+
+    ---
+
+    Homebrew/brew#18662
+
+-   ![](https://github.com/NetApp.png?size=40){ width="40" loading=lazy align=left } NetApp/harvest
+
+    ---
+
+    NetApp/harvest#3247
+
+-   ![](https://github.com/PyO3.png?size=40){ width="40" loading=lazy align=left } PyO3/pyo3
+
+    ---
+
+    PyO3/pyo3#4774
+
+-   ![](https://github.com/adafruit.png?size=40){ width="40" loading=lazy align=left } adafruit/circuitpython
+
+    ---
+
+    adafruit/circuitpython#9785
+
+-   ![](https://github.com/astral-sh.png?size=40){ width="40" loading=lazy align=left } astral-sh/ruff
+
+    ---
+
+    astral-sh/ruff#14844
+
+-   ![](https://github.com/astropy.png?size=40){ width="40" loading=lazy align=left } astropy/astropy
+
+    ---
+
+    astropy/astropy#17315
+
+-   ![](https://github.com/danmar.png?size=40){ width="40" loading=lazy align=left } danmar/cppcheck
+
+    ---
+
+    danmar/cppcheck#7044
+
+-   ![](https://github.com/hugovk.png?size=40){ width="40" loading=lazy align=left } hugovk/em-keyboard
+
+    ---
+
+    hugovk/em-keyboard#148
+
+-   ![](https://github.com/hugovk.png?size=40){ width="40" loading=lazy align=left } hugovk/norwegianblue
+
+    ---
+
+    hugovk/norwegianblue#233
+
+-   ![](https://github.com/hugovk.png?size=40){ width="40" loading=lazy align=left } hugovk/pypistats
+
+    ---
+
+    hugovk/pypistats#460
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/argon2-cffi
+
+    ---
+
+    hynek/argon2-cffi#185
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/doc2dash
+
+    ---
+
+    hynek/doc2dash#225
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/environ-config
+
+    ---
+
+    hynek/environ-config#88
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/hatch-fancy-pypi-readme
+
+    ---
+
+    hynek/hatch-fancy-pypi-readme#57
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/pem
+
+    ---
+
+    hynek/pem#100
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/prometheus-async
+
+    ---
+
+    hynek/prometheus-async#70
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/stamina
+
+    ---
+
+    hynek/stamina#81
+
+-   ![](https://github.com/hynek.png?size=40){ width="40" loading=lazy align=left } hynek/structlog
+
+    ---
+
+    hynek/structlog#663
+
+-   ![](https://github.com/marcusvolz.png?size=40){ width="40" loading=lazy align=left } marcusvolz/strava_py
+
+    ---
+
+    marcusvolz/strava_py#53
+
+-   ![](https://github.com/matplotlib.png?size=40){ width="40" loading=lazy align=left } matplotlib/matplotlib
+
+    ---
+
+    matplotlib/matplotlib#29251
+
+-   ![](https://github.com/praetorian-inc.png?size=40){ width="40" loading=lazy align=left } praetorian-inc/noseyparker
+
+    ---
+
+    praetorian-inc/noseyparker#228
+
+-   ![](https://github.com/prettytable.png?size=40){ width="40" loading=lazy align=left } prettytable/prettytable
+
+    ---
+
+    prettytable/prettytable#339
+
+-   ![](https://github.com/pyca.png?size=40){ width="40" loading=lazy align=left } pyca/service-identity
+
+    ---
+
+    pyca/service-identity#75
+
+-   ![](https://github.com/pylast.png?size=40){ width="40" loading=lazy align=left } pylast/pylast
+
+    ---
+
+    pylast/pylast#465
+
+-   ![](https://github.com/pypa.png?size=40){ width="40" loading=lazy align=left } pypa/pip-audit
+
+    ---
+
+    pypa/pip-audit#851
+
+-   ![](https://github.com/python-attrs.png?size=40){ width="40" loading=lazy align=left } python-attrs/attrs
+
+    ---
+
+    python-attrs/attrs#1368
+
+-   ![](https://github.com/python-attrs.png?size=40){ width="40" loading=lazy align=left } python-attrs/cattrs
+
+    ---
+
+    python-attrs/cattrs#605
+
+-   ![](https://github.com/python-humanize.png?size=40){ width="40" loading=lazy align=left } python-humanize/humanize
+
+    ---
+
+    python-humanize/humanize#221
+
+-   ![](https://github.com/python-pillow.png?size=40){ width="40" loading=lazy align=left } python-pillow/Pillow
+
+    ---
+
+    python-pillow/Pillow#8526
+
+-   ![](https://github.com/python.png?size=40){ width="40" loading=lazy align=left } python/cpython
+
+    ---
+
+    python/cpython#127749
+
+-   ![](https://github.com/python.png?size=40){ width="40" loading=lazy align=left } python/miss-islington
+
+    ---
+
+    python/miss-islington#705
+
+-   ![](https://github.com/rust-lang.png?size=40){ width="40" loading=lazy align=left } rust-lang/crates.io
+
+    ---
+
+    rust-lang/crates.io#10176
+
+-   ![](https://github.com/rustls.png?size=40){ width="40" loading=lazy align=left } rustls/rustls
+
+    ---
+
+    rustls/rustls#2261
+
+-   ![](https://github.com/rustls.png?size=40){ width="40" loading=lazy align=left } rustls/tokio-rustls
+
+    ---
+
+    rustls/tokio-rustls#96
+
+-   ![](https://github.com/sigstore.png?size=40){ width="40" loading=lazy align=left } sigstore/cosign
+
+    ---
+
+    sigstore/cosign#3959
+
+-   ![](https://github.com/sigstore.png?size=40){ width="40" loading=lazy align=left } sigstore/gitsign
+
+    ---
+
+    sigstore/gitsign#602
+
+-   ![](https://github.com/termcolor.png?size=40){ width="40" loading=lazy align=left } termcolor/termcolor
+
+    ---
+
+    termcolor/termcolor#89
+
+-   ![](https://github.com/tornadoweb.png?size=40){ width="40" loading=lazy align=left } tornadoweb/tornado
+
+    ---
+
+    tornadoweb/tornado#3438
+
+-   ![](https://github.com/vlang.png?size=40){ width="40" loading=lazy align=left } vlang/v
+
+    ---
+
+    vlang/v#22681
diff --git a/docs/snippets/trophies.txt b/docs/snippets/trophies.txt
@@ -0,0 +1,46 @@
+# one per line, order is not important
+# trophies MUST be formatted as owner/repo#number,
+# where owner/repo is the GitHub repo slug and
+# number is the issue/PR that introduces or uses zizmor
+
+adafruit/circuitpython#9785
+astral-sh/ruff#14844
+astropy/astropy#17315
+danmar/cppcheck#7044
+DataDog/datadog-agent#30871
+Diaoul/subliminal#1190
+Homebrew/brew#18662
+hugovk/em-keyboard#148
+hugovk/norwegianblue#233
+hugovk/pypistats#460
+hynek/argon2-cffi#185
+hynek/doc2dash#225
+hynek/environ-config#88
+hynek/hatch-fancy-pypi-readme#57
+hynek/pem#100
+hynek/prometheus-async#70
+hynek/stamina#81
+hynek/structlog#663
+matplotlib/matplotlib#29251
+marcusvolz/strava_py#53
+NetApp/harvest#3247
+praetorian-inc/noseyparker#228
+prettytable/prettytable#339
+pyca/service-identity#75
+pylast/pylast#465
+pypa/pip-audit#851
+python/cpython#127749
+python/miss-islington#705
+python-attrs/attrs#1368
+python-attrs/cattrs#605
+python-humanize/humanize#221
+python-pillow/Pillow#8526
+PyO3/pyo3#4774
+rust-lang/crates.io#10176
+rustls/rustls#2261
+rustls/tokio-rustls#96
+sigstore/cosign#3959
+sigstore/gitsign#602
+termcolor/termcolor#89
+tornadoweb/tornado#3438
+vlang/v#22681