paperplot — publication-correct matplotlib figures

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zlatko-minev

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  # Keep GitHub Actions current; pair with SHA-pinning for supply-chain hardening.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "ci"
+
+  # Python dependency bumps for the package + extras.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "deps"

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least privilege: tests/builds only need to read the repo (caps the token even
+# if a matrix dependency or action is compromised).
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # Cross-platform smoke on the current default Python (keeps the grid small).
+        include:
+          - { os: macos-latest, python-version: "3.12" }
+          - { os: windows-latest, python-version: "3.12" }
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    env:
+      MPLBACKEND: Agg
+      PYTHONUTF8: "1"        # UTF-8 mode so Unicode output works on Windows consoles
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install (with dev + optional extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,notebook,seaborn]"
+
+      - name: Run tests
+        run: pytest -q
+
+      - name: Render examples headless (smoke test)
+        run: python examples/run_all.py
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Default to read-only; the elevated Pages/OIDC scopes are granted only to the
+# deploy job below, so fork-PR builds run with a read-only token.
+permissions:
+  contents: read
+
+# PR builds get a fast, per-ref cancellable group; the deploy job uses the global
+# `pages` group (set on the job) so concurrent deploys serialize.
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package + docs deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs,notebook]"
+
+      - name: Generate gallery (runs the showcase headless)
+        env:
+          MPLBACKEND: Agg
+        run: python docs/generate_gallery.py
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  # Deploy only from main; PRs build (above) to catch breakage without publishing.
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    # Elevated scopes live here only — never on PR builds.
+    permissions:
+      pages: write
+      id-token: write
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ipynb_checkpoints/
+
+# Generated example outputs
+examples/out/
+
+# MkDocs build output (docs/assets/gallery/ IS tracked — committed gallery images)
+site/
+.cache/
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/
+*.code-workspace
+
+# Claude Code personal settings
+.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,42 @@
+# paperplot — notes for agents
+
+Publication-correct matplotlib figures, sized/styled/preflighted per journal
+(APS + Nature + IEEE, plus a `talk` presentation target). Small library; keep it small.
+
+## Commands
+- Tests: `pytest` (Agg backend; fixtures snapshot/restore rcParams — keep that pattern).
+- Examples: `python examples/showcase.py` or `python examples/run_all.py`
+  → writes PDFs to `examples/out/` and PNG proofs to `examples/out/render/` (gitignored).
+- Dev install: `pip install -e ".[dev]"`. Python ≥ 3.10.
+
+## Hard rules (don't break these)
+- **matplotlib-only core.** `numpy` + `matplotlib` are the only runtime deps.
+  `seaborn` and `IPython` are OPTIONAL extras — import them lazily *inside* the
+  function that needs them, behind a try/guard. Never add a top-level `import
+  seaborn`/`IPython`. (`plots.hist_outline` has the one opt-in seaborn path.)
+- **Journals are data, not code.** Add/edit journal specs in
+  `paperplot/data/journals.toml`, loaded via `registry.py` — not hardcoded.
+- **`__init__.py` is the public API contract.** Anything users call must be
+  re-exported there and listed in `__all__`. Keep imports + `__all__` in sync.
+- **`plots.py` is a deliberately small set** of opinionated composites
+  (hist_outline/hist_filled, data_fit_band, swatches/show_palettes). It is NOT a
+  general plotting library — no dataframes, faceting, or grammar-of-graphics.
+  See the "Scope amendment" note in `paperplot_DESIGN.md`.
+- **preflight warns, never blocks.** `save()`/`preflight()` always produce output
+  and surface a `Report`; no raising/strict mode.
+- **`.mplstyle` export is an on-ramp, not the product.** `mplstyle.py` renders the
+  *look* (rcParams) for `plt.style.use`; it cannot size/embed/preflight, so never
+  route core sizing through it. `register_mplstyles()` mutates matplotlib's global
+  style library — keep it opt-in; NEVER auto-register on import (silent first import).
+  Hex colors in the file text are written without `#` (it's a comment char there).
+
+## Conventions
+- Default cycle is **Okabe-Ito** (colorblind-safe). Separately, the fill/stroke
+  convention: `pp.fills()` (muted) for areas, `pp.strokes()` (bright) for lines —
+  these are NOT colorblind-safe; don't make them the categorical default.
+- Sequential/diverging colormaps go through `pp.cmap(...)`, never the categorical
+  cycle (palettes.py enforces this with a warning).
+
+## Source of truth
+`paperplot_DESIGN.md` records the design decisions and trade-offs — read it before
+changing architecture (registry/versioning, rcParams mapping, journal model).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The paperplot authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.