plotstyle 1.0.0__tar.gz → 1.2.0__tar.gz

{plotstyle-1.0.0 → plotstyle-1.2.0}/.gitignore

@@ -157,3 +157,6 @@ celerybeat-schedule
 
 # secrets (just in case)
 secrets.json
+
+# local files
+local/

{plotstyle-1.0.0 → plotstyle-1.2.0}/CHANGELOG.md

@@ -13,6 +13,61 @@ _Nothing yet._
 
 ---
 
+## [1.2.0] - 2026-04-23
+
+Feature release: **overlays**, **units & conversions**, **Seaborn integration**, improved **font/LaTeX controls**, plus major CLI/docs/example expansion.
+
+### Added
+
+- **Style overlays** (`plotstyle.overlays`, `plotstyle.list_overlays()`): additive layers that can be composed with a base journal preset.
+  - Categories: `color`, `context`, `rendering`, `plot-type`, `script`.
+  - Built-in overlays include `minimal`, `notebook`, `presentation`, `high-vis`, `grid`, `bar`, `scatter`, `no-latex`, `pgf`, `latex-sans`, `okabe-ito`, `safe-grayscale`, and `tol-*` palette overlays, plus CJK/Turkish/Russian script overlays.
+- **New CLI commands for overlays**
+  - `plotstyle overlays [--category <category>]` to list overlays.
+  - `plotstyle overlay-info <overlay>` to inspect overlay metadata and `rcParams`.
+- **Font checks for overlays**: `plotstyle fonts --overlay <overlay>` (in addition to `--journal`).
+- **Seaborn integration**: helpers to keep PlotStyle `rcParams` consistent when using Seaborn themes (`patch_seaborn()`, `plotstyle_theme()`, `unpatch_seaborn()`).
+- **Units & conversions**: new/expanded utilities and docs for consistent size specification across specs and helpers.
+- **Matplotlib-native styles compatibility**: support for registering/using PlotStyle presets as Matplotlib styles where applicable.
+- **New examples & previews**: additional example scripts including overlays, Seaborn integration, units/conversions, print-size preview, Matplotlib native styles, and LaTeX/fonts.
+
+### Changed
+
+- **CLI UX improvements**
+  - `plotstyle fonts` now supports `--journal` *or* `--overlay` (mutually exclusive, required).
+  - More robust argument parsing (e.g. ignores empty entries in `--formats`).
+  - Friendlier output for empty registries (journals/overlays) and clearer reporting for overlay font availability.
+- **Docs & README expansion**: new/expanded guides and API reference for overlays, units, warnings, Seaborn, preview tooling, and updated patterns/examples.
+
+### Fixed
+
+- **CLI stability**: avoid noisy/unclear behavior in edge cases (empty registry listings, malformed format lists) and improve error messaging around missing overlay keys.
+
+---
+
+## [1.1.0] - 2026-04-16
+
+Minor feature release : ergonomics improvements, hardened error handling, and spec updates.
+
+### Added
+
+- **`quiet` parameter on `JournalStyle.export()`** : suppresses compliance summaries and manifest output for scripting workflows.
+- **Pre-computed Type 3 font checks** : compliance summary now accepts a pre-computed result for Type 3 font detection, improving performance when the check has already been run by the caller.
+- **`JournalSpec` key access** : `JournalSpec` now supports key-style access, and the dimension check message has been updated for clarity.
+
+### Fixed
+
+- **`SpecNotFoundError` base classes** : now inherits from both `ValueError` and `KeyError` so existing `except ValueError` and `except KeyError` handlers catch it correctly; a custom `__str__` produces clearer diagnostic messages.
+
+### Changed
+
+- **IEEE Transactions spec updated** : column widths, max height, font family, panel-label properties, and preferred output formats revised to match current IEEE author guidelines.
+- **CI documentation build** : Sphinx `docs` job (`sphinx-build -W -n`) added to the CI workflow; rendered HTML is uploaded as an artifact on every push.
+- **Module docstrings** : expanded and standardised across `__init__.py`, `_utils/`, `color/`, `core/`, and `validation/` for consistent Sphinx rendering.
+- **Context-manager examples** : all `plotstyle.use()` call sites in docs and examples updated to the `with plotstyle.use(...) as style:` form to ensure correct `rcParams` restoration.
+
+---
+
 ## [1.0.0] - 2026-04-12
 
 First stable release — production-ready for scientific publication workflows.
@@ -72,7 +127,9 @@ First public alpha release.
 - **Dynamic versioning** — version derived from git tags via `hatch-vcs` and `importlib.metadata`.
 - **CI/CD pipeline** — GitHub Actions workflows for lint, type-check, test matrix, and automated PyPI release via OIDC Trusted Publishing.
 
-[Unreleased]: https://github.com/rahulkaushal04/plotstyle/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/rahulkaushal04/plotstyle/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/rahulkaushal04/plotstyle/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/rahulkaushal04/plotstyle/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/rahulkaushal04/plotstyle/compare/v0.1.0a2...v1.0.0
 [0.1.0a2]: https://github.com/rahulkaushal04/plotstyle/compare/v0.1.0a1...v0.1.0a2
 [0.1.0a1]: https://github.com/rahulkaushal04/plotstyle/releases/tag/v0.1.0a1

plotstyle-1.2.0/PKG-INFO

@@ -0,0 +1,594 @@
+Metadata-Version: 2.4
+Name: plotstyle
+Version: 1.2.0
+Summary: Matplotlib/seaborn style presets matching scientific journal requirements, with validation, export safety, and preview capabilities.
+Project-URL: Homepage, https://github.com/rahulkaushal04/plotstyle
+Project-URL: Documentation, https://plotstyle.readthedocs.io
+Project-URL: Repository, https://github.com/rahulkaushal04/plotstyle
+Project-URL: Issues, https://github.com/rahulkaushal04/plotstyle/issues
+Project-URL: Changelog, https://github.com/rahulkaushal04/plotstyle/blob/main/CHANGELOG.md
+Project-URL: Download, https://pypi.org/project/plotstyle/
+Author: Rahul Kaushal
+License: MIT License
+        
+        Copyright (c) 2026 Rahul Kaushal
+        
+        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.
+License-File: LICENSE
+Keywords: academic,accessibility,colorblind,export,figures,ieee,journal,matplotlib,nature,plotting,publication,rcParams,research,science,scientific,seaborn,style,typesetting,validation,visualization
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Matplotlib
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: matplotlib<4,>=3.9
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: fonttools<5,>=4.55; extra == 'all'
+Requires-Dist: pandas<3,>=2.2; extra == 'all'
+Requires-Dist: pillow<13,>=11.0; extra == 'all'
+Requires-Dist: seaborn<1,>=0.13.2; extra == 'all'
+Provides-Extra: color
+Requires-Dist: pillow<13,>=11.0; extra == 'color'
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pillow<13,>=11.0; extra == 'dev'
+Requires-Dist: pre-commit<5,>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6.0; extra == 'dev'
+Requires-Dist: pytest-mpl<1,>=0.18; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.15; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2025.12.19; extra == 'docs'
+Requires-Dist: myst-parser<6,>=5.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints<4,>=3.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton<1,>=0.5; extra == 'docs'
+Requires-Dist: sphinx<10,>=9.0; extra == 'docs'
+Provides-Extra: fonttools
+Requires-Dist: fonttools<5,>=4.55; extra == 'fonttools'
+Provides-Extra: seaborn
+Requires-Dist: pandas<3,>=2.2; extra == 'seaborn'
+Requires-Dist: seaborn<1,>=0.13.2; extra == 'seaborn'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <strong>plotstyle</strong>
+</p>
+
+<p align="center">
+  <em>Matplotlib figures formatted for journal submission, automatically.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/plotstyle/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/plotstyle?color=blue"></a>
+  <a href="https://pypi.org/project/plotstyle/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/plotstyle"></a>
+  <a href="https://github.com/rahulkaushal04/plotstyle/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/rahulkaushal04/plotstyle"></a>
+  <a href="https://github.com/rahulkaushal04/plotstyle/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/rahulkaushal04/plotstyle/ci.yml?label=CI"></a>
+  <a href="https://plotstyle.readthedocs.io/en/stable/"><img alt="Docs" src="https://img.shields.io/readthedocs/plotstyle/stable?label=docs"></a>
+</p>
+
+---
+
+**PlotStyle** makes it easy to produce Matplotlib figures that meet the exact typographic, dimensional, and export requirements of major academic journals. It also integrates with Seaborn, with more integrations planned. Pick a journal, create your figure, save it. PlotStyle handles the rest.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Examples](#examples)
+  - [Multi-panel figures](#multi-panel-figures)
+  - [Color palettes](#color-palettes)
+  - [Overlays](#overlays)
+  - [Colorblind and grayscale previews](#colorblind-and-grayscale-previews)
+  - [Validation and submission export](#validation-and-submission-export)
+- [Supported Journals](#supported-journals)
+- [CLI](#cli)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [Citation](#citation)
+- [License](#license)
+
+---
+
+## Installation
+
+Requires **Python 3.10+** and **Matplotlib >= 3.9**.
+
+```bash
+pip install plotstyle
+```
+
+Optional extras:
+
+```bash
+pip install "plotstyle[color]"     # colorblind / grayscale previews
+pip install "plotstyle[seaborn]"   # seaborn integration
+pip install "plotstyle[all]"       # everything
+```
+
+---
+
+## Quick Start
+
+```python
+import numpy as np
+import plotstyle
+
+with plotstyle.use("nature") as style:
+    fig, ax = style.figure(columns=1)   # sized to Nature's single-column width (89 mm)
+
+    x = np.linspace(0, 2 * np.pi, 200)
+    ax.plot(x, np.sin(x), label="sin(x)")
+    ax.plot(x, np.cos(x), label="cos(x)")
+    ax.set_xlabel("Phase (rad)")
+    ax.set_ylabel("Amplitude (a.u.)")
+    ax.legend()
+
+    style.savefig(fig, "figure.pdf")    # 300 DPI minimum, TrueType fonts embedded
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/quickstart_nature.png" width="55%" alt="Quickstart output: sin and cos figure styled for Nature">
+</p>
+
+The `with` block is the recommended pattern. Matplotlib's `rcParams` are restored automatically when it exits, even if an exception occurs.
+
+---
+
+## Examples
+
+### Multi-panel figures
+
+`style.subplots()` works like `plt.subplots()` but sizes the figure to the journal spec and adds panel labels automatically. All built-in journal specs use bold lowercase labels (**a**, **b**, **c**, …). The label style is driven by each spec's `panel_label_case` field and can be `lower`, `upper`, `parens_lower`, `parens_upper`, `sentence`, or `title`.
+
+```python
+import numpy as np
+import plotstyle
+
+rng = np.random.default_rng(42)
+
+with plotstyle.use("science") as style:
+    fig, axes = style.subplots(nrows=2, ncols=2, columns=2)
+
+    x = np.linspace(0, 10, 100)
+    axes[0, 0].plot(x, np.sin(x), label="sin")
+    axes[0, 0].plot(x, np.cos(x), label="cos")
+    axes[0, 0].set_xlabel("x")
+    axes[0, 0].set_ylabel("f(x)")
+    axes[0, 0].legend()
+
+    xs = rng.normal(0, 1, 60)
+    ys = 0.7 * xs + rng.normal(0, 0.3, 60)
+    axes[0, 1].scatter(xs, ys, s=12, alpha=0.7)
+    axes[0, 1].set_xlabel("Variable X")
+    axes[0, 1].set_ylabel("Variable Y")
+
+    axes[1, 0].bar(["A", "B", "C", "D"], [3.2, 5.8, 4.1, 6.5])
+    axes[1, 0].set_xlabel("Category")
+    axes[1, 0].set_ylabel("Count")
+
+    axes[1, 1].hist(rng.normal(0, 1, 500), bins=25, edgecolor="white", linewidth=0.5)
+    axes[1, 1].set_xlabel("Value")
+    axes[1, 1].set_ylabel("Frequency")
+
+    style.savefig(fig, "multi_panel.pdf")
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/multi_panel_science.png" width="70%" alt="2x2 multi-panel Science figure with automatic panel labels a b c d">
+</p>
+
+> `axes` is always a 2-D NumPy array. Use `axes[0, 0]` to access a single panel or `axes.flat` to iterate. Pass `panels=False` to suppress the automatic labels.
+
+---
+
+### Color palettes
+
+Each journal has a recommended colorblind-safe palette. `plotstyle.palette()` returns hex color strings, cycling if you need more than the palette length.
+
+```python
+import matplotlib.pyplot as plt
+import plotstyle
+
+journals = ["nature", "science", "ieee", "acs"]
+fig, axes = plt.subplots(len(journals), 1, figsize=(6, 0.6 * len(journals)))
+
+for ax, journal in zip(axes, journals, strict=False):
+    pal = plotstyle.palette(journal, n=8)
+    for i, color in enumerate(pal):
+        ax.barh(0, 1, left=i, color=color, edgecolor="none", height=0.8)
+    ax.set_xlim(0, 8)
+    ax.set_yticks([])
+    ax.set_ylabel(journal, rotation=0, ha="right", va="center")
+    ax.set_xticks([])
+
+fig.suptitle("Journal Color Palettes")
+fig.tight_layout()
+fig.savefig("palette_comparison.png", dpi=150)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/palette_comparison.png" width="70%" alt="Color swatch comparison for Nature, Science, IEEE, and ACS palettes">
+</p>
+
+Pass `with_markers=True` to get `(color, linestyle, marker)` tuples, useful for journals like IEEE that print in grayscale:
+
+```python
+styled = plotstyle.palette("ieee", n=4, with_markers=True)
+for color, ls, marker in styled:
+    ax.plot(x, y, color=color, linestyle=ls, marker=marker)
+```
+
+```text
+# styled — one (color, linestyle, marker) tuple per series:
+[('#000000', '-', 'o'), ('#333333', '--', 's'), ('#666666', '-.', '^'), ('#999999', ':', 'D')]
+```
+
+---
+
+### Overlays
+
+Overlays are additive patches that layer on top of a journal preset. They let you adjust one aspect of a figure — the colour palette, the context, the chart type — without changing the base journal settings.
+
+Pass overlay names in the same list as the journal key:
+
+```python
+import plotstyle
+
+# Strip top/right spines for a clean editorial look
+with plotstyle.use(["nature", "minimal"]) as style:
+    fig, ax = style.figure(columns=1)
+    ax.plot([1, 2, 3])
+    style.savefig(fig, "figure.pdf")
+
+# Larger figure and fonts for Jupyter notebooks
+with plotstyle.use(["nature", "notebook"]) as style:
+    import matplotlib.pyplot as plt
+    fig, ax = plt.subplots()   # plt.subplots() picks up the notebook figsize
+    ax.plot([1, 2, 3])
+
+# Swap the colour cycle to a specific palette
+with plotstyle.use(["ieee", "okabe-ito"]) as style:
+    fig, ax = style.figure(columns=1)
+    ax.plot([1, 2, 3])
+```
+
+| Category | Purpose | Examples |
+|----------|---------|---------|
+| `color` | Swap the colour cycle | `okabe-ito`, `tol-bright`, `safe-grayscale` |
+| `context` | Adjust scale for the medium | `notebook`, `presentation`, `minimal`, `high-vis` |
+| `rendering` | Control LaTeX and grid rendering | `no-latex`, `grid`, `latex-sans`, `pgf` |
+| `plot-type` | Optimise for a chart type | `bar`, `scatter` |
+| `script` | Non-Latin font support | `cjk-simplified`, `russian`, `turkish` |
+
+```python
+# List all available overlays
+plotstyle.list_overlays()
+plotstyle.list_overlays(category="context")
+```
+
+```text
+# plotstyle.list_overlays()
+['bar', 'cjk-japanese', 'cjk-korean', 'cjk-simplified', 'cjk-traditional', 'grid',
+ 'high-vis', 'latex-sans', 'minimal', 'no-latex', 'notebook', 'okabe-ito', 'pgf',
+ 'presentation', 'russian', 'safe-grayscale', 'scatter', 'tol-bright',
+ 'tol-high-contrast', 'tol-light', 'tol-muted', 'tol-rainbow-10', 'tol-rainbow-12',
+ 'tol-rainbow-4', 'tol-rainbow-6', 'tol-rainbow-8', 'tol-vibrant', 'turkish']
+
+# plotstyle.list_overlays(category="context")
+['high-vis', 'minimal', 'notebook', 'presentation']
+```
+
+---
+
+### Colorblind and grayscale previews
+
+Build a figure, then simulate how it looks under color vision deficiency or grayscale printing before you submit.
+
+```python
+import numpy as np
+import plotstyle
+
+with plotstyle.use("nature") as style:
+    colors = style.palette(n=4)
+    fig, ax = style.figure(columns=1)
+    x = np.linspace(0, 5, 80)
+    for i, c in enumerate(colors):
+        ax.plot(x, np.sin(x + i), color=c, linewidth=1.5, label=f"Series {i + 1}")
+    ax.set_xlabel("Time (s)")
+    ax.set_ylabel("Signal")
+    ax.legend()
+
+    # Simulate colour vision deficiency (deuteranopia, protanopia, tritanopia)
+    cvd_fig = plotstyle.preview_colorblind(fig)
+    cvd_fig.savefig("accessibility_colorblind.png", dpi=150, bbox_inches="tight")
+
+    # Simulate grayscale print
+    gray_fig = plotstyle.preview_grayscale(fig)
+    gray_fig.savefig("accessibility_grayscale.png", dpi=150, bbox_inches="tight")
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/accessibility_colorblind.png" width="90%" alt="Colorblind simulation: original, deuteranopia, protanopia, tritanopia">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahulkaushal04/plotstyle/main/examples/output/accessibility_grayscale.png" width="60%" alt="Grayscale simulation: original vs grayscale rendering">
+</p>
+
+---
+
+### Validation and submission export
+
+Validate a figure against the journal's requirements, then export in all required formats at once.
+
+```python
+report = plotstyle.validate(fig, journal="nature")
+print(report)          # formatted compliance table
+print(report.passed)   # True if everything is OK
+
+for failure in report.failures:
+    print(failure.message)         # what failed
+    print(failure.fix_suggestion)  # how to fix it
+```
+
+```text
+┌──────────────────────────────────────────────────────┐
+│         PlotStyle Validation Report — Nature         │
+├──────────┬───────────────────────────────────────────┤
+│ ✓ PASS   │ Figure width 89.0mm matches single colu...│
+│ ✓ PASS   │ Figure height 55.0mm is within the Natu...│
+│ ✗ FAIL   │ pdf.fonttype = 3; must be 42 for TrueTy...│
+│ ✗ FAIL   │ ps.fonttype = 3; must be 42 for TrueTyp...│
+│ ⚠ WARN   │ savefig.dpi = 'figure'; Nature requires...│
+│ ✓ PASS   │ All plotted lines and spines meet the N...│
+│ ✗ FAIL   │ 14 text element(s) outside the Nature r...│
+└──────────┴───────────────────────────────────────────┘
+3/7 checks passed, 1 warning(s), 3 failure(s)
+
+passed: False
+
+failure.message:       pdf.fonttype = 3; must be 42 for TrueType font embedding.
+failure.fix_suggestion: Call plotstyle.use() to apply all required rcParams, or set
+                        mpl.rcParams['pdf.fonttype'] = 42 manually.
+```
+
+When called inside `plotstyle.use()`, all checks pass:
+
+```text
+┌──────────────────────────────────────────────────────┐
+│         PlotStyle Validation Report — Nature         │
+├──────────┬───────────────────────────────────────────┤
+│ ✓ PASS   │ Figure width 89.0mm matches single colu...│
+│ ✓ PASS   │ Figure height 55.0mm is within the Natu...│
+│ ✓ PASS   │ pdf.fonttype = 42 (TrueType fonts will ...│
+│ ✓ PASS   │ ps.fonttype = 42 (TrueType fonts will b...│
+│ ✓ PASS   │ savefig.dpi = 300.0 meets the Nature mi...│
+│ ✓ PASS   │ All plotted lines and spines meet the N...│
+│ ✓ PASS   │ All text elements are within the Nature...│
+└──────────┴───────────────────────────────────────────┘
+7/7 checks passed, 0 warning(s), 0 failure(s)
+
+passed: True
+```
+
+```python
+paths = plotstyle.export_submission(
+    fig,
+    "figure1",
+    journal="ieee",
+    author_surname="Smith",     # IEEE prepends the surname prefix to filenames
+    output_dir="submission/",
+)
+print(paths)
+```
+
+```text
+[PosixPath('submission/smith_figure1.tiff'),
+ PosixPath('submission/smith_figure1.eps'),
+ PosixPath('submission/smith_figure1.pdf'),
+ PosixPath('submission/smith_figure1.png')]
+```
+
+---
+
+## Supported Journals
+
+| Key | Journal | Publisher |
+|-----|---------|-----------|
+| `acs` | ACS (JACS) | American Chemical Society |
+| `cell` | Cell | Cell Press |
+| `elsevier` | Elsevier | Elsevier |
+| `ieee` | IEEE Transactions | IEEE |
+| `nature` | Nature | Springer Nature |
+| `plos` | PLOS ONE | Public Library of Science |
+| `prl` | Physical Review Letters | American Physical Society |
+| `science` | Science | AAAS |
+| `springer` | Springer | Springer |
+| `wiley` | Wiley | Wiley |
+
+> Need another journal? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## CLI
+
+```
+plotstyle list                                 # list all journal presets
+plotstyle info <journal>                       # show spec details
+plotstyle diff <journal_a> <journal_b>         # compare two journals
+plotstyle fonts --journal <journal>            # check font availability
+plotstyle overlays [--category <category>]    # list available overlays
+plotstyle overlay-info <overlay>               # show overlay details
+plotstyle validate <file> --journal <journal>  # validate a saved figure
+plotstyle export <file> --journal <journal>    # print snippet for re-exporting
+```
+
+**`plotstyle list`**
+```text
+  acs             American Chemical Society
+  cell            Cell Press
+  elsevier        Elsevier
+  ieee            IEEE
+  nature          Springer Nature
+  plos            Public Library of Science
+  prl             American Physical Society
+  science         AAAS
+  springer        Springer Nature
+  wiley           Wiley
+```
+
+**`plotstyle info nature`**
+```text
+Journal: Nature
+Publisher: Springer Nature
+Source: https://www.nature.com/documents/nature-final-artwork.pdf
+Last Verified: 2026-04-22
+──────────────────────────
+Dimensions:
+  Single column: 89.0mm (3.50in)
+  Double column: 183.0mm (7.20in)
+  Max height:    247.0mm
+Typography:
+  Font:          Helvetica, Arial (fallback: sans-serif)
+  Size range:    5.0-7.0pt
+  Panel labels:  5.0pt bold lower (a, b, c)
+Export:
+  Formats:  ai, eps, pdf
+  Min DPI:  300
+  Color:    rgb
+Accessibility:
+  Colorblind safe: Not required
+  Grayscale safe:  Not required
+```
+
+**`plotstyle diff nature science`**
+```text
+Nature → Science
+──────────────────────────────────────────────────
+Column Width (single):  89.0mm → 86.4mm
+Column Width (double):  183.0mm → 177.8mm
+Max Height:             247.0mm → —
+Font Family:            Helvetica, Arial → Minion Pro, Benton Sans Condensed
+Min Font Size:          5.0pt → 7.5pt
+Max Font Size:          7.0pt → 10.0pt
+Panel Label Size:       5.0pt → 7.5pt
+Preferred Formats:      ai, eps, pdf → ai, eps, pdf, tiff
+Colorblind Required:    No → Yes
+```
+
+**`plotstyle fonts --journal nature`**
+```text
+Font check for: Nature
+Required:        Helvetica, Arial
+Available:       Helvetica, Arial
+Selected:        Helvetica
+Exact match:     Yes
+```
+
+**`plotstyle overlays`**
+```text
+  bar             [plot-type]  Optimised rcParams for bar charts.
+  cjk-simplified  [script]     Font configuration for Simplified Chinese labels.
+  grid            [rendering]  Enable major grid lines with a subtle dashed style.
+  high-vis        [context]    Maximum contrast, bold lines, and oversized ticks.
+  latex-sans      [rendering]  Enable LaTeX rendering with a sans-serif font family.
+  minimal         [context]    Stripped-down axes with no top/right spines.
+  no-latex        [rendering]  Disable LaTeX text rendering; use Matplotlib MathText.
+  notebook        [context]    Enlarged figures and larger fonts for Jupyter.
+  okabe-ito       [color]      Colorblind-safe 8-color qualitative palette.
+  pgf             [rendering]  Use the PGF LaTeX backend for vector output.
+  presentation    [context]    Large text and thick lines for slide decks.
+  safe-grayscale  [color]      6-step grayscale palette for black-and-white print.
+  scatter         [plot-type]  Optimised rcParams for scatter plots.
+  tol-bright      [color]      Paul Tol's bright 7-color qualitative palette.
+  ...
+```
+
+**`plotstyle overlay-info minimal`**
+```text
+Overlay: Minimal
+Key:     minimal
+Category: context
+Description: Stripped-down axes with no top/right spines for editorial and blog use.
+──────────────────────────
+rcParams:
+  axes.spines.top = False
+  axes.spines.right = False
+  xtick.top = False
+  ytick.right = False
+  axes.grid = False
+  axes.linewidth = 0.8
+```
+
+---
+
+## Documentation
+
+Full documentation at **[plotstyle.readthedocs.io](https://plotstyle.readthedocs.io)**:
+
+- [Installation guide](https://plotstyle.readthedocs.io/en/stable/installation.html)
+- [Quick start tutorial](https://plotstyle.readthedocs.io/en/stable/quickstart.html)
+- [API reference](https://plotstyle.readthedocs.io/en/stable/api/index.html)
+- [CLI reference](https://plotstyle.readthedocs.io/en/stable/cli.html)
+- [FAQ](https://plotstyle.readthedocs.io/en/stable/faq.html)
+
+Working examples are in the [`examples/`](examples/) directory.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, adding journal specs, and pull request guidelines.
+
+---
+
+## Citation
+
+If PlotStyle helps your research, a citation or star is appreciated:
+
+```bibtex
+@misc{plotstyle,
+  author  = {Kaushal, Rahul},
+  title   = {PlotStyle: Publication-ready scientific figure presets for Matplotlib},
+  year    = {2026},
+  url     = {https://github.com/rahulkaushal04/plotstyle},
+  note    = {Version 1.2.0},
+}
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Rahul Kaushal