Docs/CI: Self-Contained Weekly Metrics SVG Generator

[Borda]

Overview

Implement an automated weekly CI process that tracks download counts and star growth, calculates week-over-week deltas, and updates a single self-contained SVG artifact. To eliminate separate state files, the historical metrics and checkpoint data must be embedded directly within the SVG metadata/comments. The workflow will update the figure via an automated Pull Request and embed it into the project documentation.

---

Key Requirements

1. Self-Contained State & Delta Engine

• No external state files: The SVG artifact must serve as both the visualization output and the single source of truth for historical checkpoints.
• Embedded Checkpoint: Embed structured JSON state directly into the SVG file structure (e.g., inside an SVG <metadata> tag or XML comment block <!-- METRICS_CHECKPOINT_DATA: {...} -->).
• Delta Computation:
  • Read previous state from existing metrics.svg.
  • Fetch current total metrics (stars, downloads) from upstream APIs.
  • Calculate weekly diffs ($\Delta \text{stars}$, $\Delta \text{downloads}$).
  • Append current period data to history and overwrite the embedded metadata block during regeneration.

2. Dual-Axis Visual Layout

• New Stars: Rendered as vertical bar series on the primary axis.
• Weekly Downloads: Rendered as a trend line overlay on the secondary axis.
• Rolling Window: Display a configurable historical range (e.g., last $N$ weeks).
• Embedded Summary: Include header metrics highlighting the most recent week-over-week change.

3. Continuous Integration & Workflow

• Trigger: Scheduled weekly CI runner (e.g., cron 0 0 * * 0).
• Pipeline Execution:
  1. Extract embedded state from target SVG in repository.
  2. Query external APIs for latest metrics.
  3. Re-render SVG graphic and serialize updated state payload into its metadata.
  4. Submit changes via automated Pull Request.

4. Documentation Integration

Embed the self-updating SVG into the documentation site and main repository landing page:

<img src="docs/assets/weekly-metrics.svg" alt="Weekly Activity and Growth Metrics" width="100%" />

---

Technical Tasks

• Implement parser/extractor to read embedded JSON state from SVG files.
• Implement SVG rendering engine handling dual-axis layout (bars + line) and metadata injection.
• Build API fetcher for stargazers and package download metrics.
• Create .github/workflows/update-metrics-svg.yml scheduled workflow.
• Add initial baseline SVG artifact to documentation directory.

[ToledoVitor]

Hi @Borda, I’d like to pick this up!

I took a look at the issue and the repo. My plan is to add a small Python script that reads the previous checkpoints from the SVG metadata, fetches the current star and download totals, calculates the weekly deltas, and regenerates the chart. I’ll also add tests and the scheduled workflow that opens an update PR.

One detail I wanted to confirm: do you have a preferred source for the cumulative PyPI download count? The current badge uses monthly data from PyPI Stats, while the issue describes taking the difference between total snapshots. PyPI’s JSON API doesn’t expose a usable download total; Pepy does, but its JSON API requires an API key. Was Pepy the intended source, or is there another provider you’d prefer?

If that direction sounds right, I’ll start from there.