docs: make the trophy case prettier (#279)

2025-12-23 08:47:33 +00:00 · 2024-12-11 22:45:27 -05:00 · 2024-12-11 22:45:27 -05:00 · 71619c4749
commit 71619c4749
parent 7c71e8157c
6 changed files with 364 additions and 49 deletions
--- a/8
+++ b/8
@ -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 > $@
--- 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

--- 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))
--- 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
--- 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
--- a/docs/trophy-case.md
+++ b/docs/trophy-case.md
@ -6,49 +6,13 @@ the software we all rely on.
 This page documents key examples where `zizmor` helped make big projects more
 secure!

-!!! important
+!!! tip "Give yourself a trophy!"

    Do you contribute to or maintain a big (>100 star) project that had its GitHub
-    Actions security improved by `zizmor`? Open a PR to add it to our list!
+    Actions security improved by `zizmor`?
+    [Add it to our list](./development.md#updating-the-trophy-case)!
+
+<div class="grid cards" markdown>
+--8<-- "trophies.md"
+</div>

-* 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