Sphinx Gallery Execution And Performance Profiling

---
name: sphinx-gallery-execution-and-performance-profiling
description: Use when you have a Sphinx-based documentation project with multiple gallery scripts (e.
license: CC-BY-4.0
metadata:
  edam_topics: []
  tools:
  - pyOpenMS-viz
  - plotly
  - Sphinx
  - Python
  - matplotlib
  - bokeh
  - pandas
  techniques:
  - mass-spectrometry
derived_from:
- doi: 10.1021/acs.jproteome.4c00873
  title: pyopenmsviz
evidence_spans:
- Chromatograms can be plotted using kind = chromatogram
- pyOpenMS-Viz is a visualization package for mass spectrometry data directly from pandas dataframes
- Multiple backends supported including matplotlib, bokeh, and plotly
- Rendering is typically slower than the BOKEH backend
- Build docs with sphinx-build
- ms_data.plot(x="m/z", y="intensity", kind="spectrum")
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_pyopenmsviz_cq
    doi: 10.1021/acs.jproteome.4c00873
    title: pyopenmsviz
  dedup_kept_from: coll_pyopenmsviz_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1021/acs.jproteome.4c00873
  all_source_dois:
  - 10.1021/acs.jproteome.4c00873
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# sphinx-gallery-execution-and-performance-profiling

## Summary

Measure and verify the aggregate execution time and memory footprint of a multi-backend Sphinx gallery by running all gallery scripts and comparing reported metrics against expected benchmarks. This skill ensures reproducibility and performance compliance across static and interactive visualization backends.

## When to use

Apply this skill when you have a Sphinx-based documentation project with multiple gallery scripts (e.g., organized by plotting backend: matplotlib, bokeh, plotly) and need to validate that the total gallery execution time matches a known reference metric or baseline, or when establishing performance budgets for documentation builds.

## When NOT to use

- When gallery scripts are not organized within a Sphinx project or do not use sphinx_gallery extension; use ad-hoc profiling (e.g., timeit, cProfile) instead.
- When only a single backend or a subset of gallery examples needs profiling; simpler profiling tools suffice for isolated script timing.
- When the reference benchmark is unknown or intentionally being established for the first time; this skill assumes a known target metric for validation.

## Inputs

- Sphinx gallery script directory tree (gallery_scripts/ with backend subdirectories)
- conf.py and gallery configuration (sphinx_gallery_conf)
- 19 example gallery scripts (Python files with docstrings and executable code blocks)
- Python 3.12 conda environment with matplotlib, bokeh, plotly, and pyOpenMS-viz installed

## Outputs

- Aggregate execution time (e.g., 00:06.221 in HH:MM.SSS format)
- Per-script execution time and memory usage metrics (from Sphinx timer)
- Exit code and build log indicating success or failure of all 19 gallery scripts
- HTML gallery documentation with rendered plots (static and interactive)

## How to apply

Clone the repository and install dependencies in a Python 3.12 conda environment. Run `sphinx-build` to execute all gallery scripts via Sphinx autosummary and autodoc, collecting execution time and memory usage metrics reported by Sphinx's built-in execution timer. Sum the per-script execution times and compare the aggregate total against the reference benchmark (e.g., 00:06.221). Verify that all 19 example files (across ms_bokeh/, ms_matplotlib/, ms_plotly/ subdirectories) complete without error. Use this workflow to detect performance regressions, memory leaks, or backend-specific bottlenecks across visualizations of mass spectrometry data types (chromatograms, spectra, peakmaps).

## Related tools

- **Sphinx** (Documentation build system and gallery executor; runs sphinx-build to invoke autosummary and autodoc, measuring per-script execution time)
- **pyOpenMS-viz** (Source library providing mass spectrometry visualization API (spectrum, chromatogram, peakmap plots) executed by gallery scripts across matplotlib, bokeh, plotly backends) — https://github.com/OpenMS/pyopenms_viz
- **matplotlib** (Static plotting backend; one of three backends tested in the gallery example suite)
- **bokeh** (Interactive plotting backend; one of three backends tested in the gallery example suite)
- **plotly** (Interactive plotting backend; one of three backends tested in the gallery example suite)
- **pandas** (Data manipulation and DataFrame interface for mass spectrometry data input to pyOpenMS-viz plot methods)
- **Python** (Runtime environment (version 3.12) for executing gallery scripts and Sphinx build system)

## Examples

```
conda create --name=pyopenms-viz python=3.12 && conda activate pyopenms-viz && git clone https://github.com/OpenMS/pyopenms_viz.git && cd pyopenms_viz && pip install -e . && sphinx-build -b html docs/ docs/_build/
```

## Evaluation signals

- Aggregate execution time reported by Sphinx matches the reference metric (00:06.221) within a tolerance (e.g., ±5%)
- All 19 gallery scripts (across ms_bokeh/, ms_matplotlib/, ms_plotly/ directories) complete without error; sphinx-build exit code is 0
- Per-script execution times are logged and individually plausible (no outliers >2× interquartile range suggesting hangs or failures)
- Memory usage metrics are captured for each script; peak memory does not exceed system limits or documented budget
- HTML gallery documentation builds successfully with all plots rendered (static matplotlib images, interactive bokeh/plotly widgets)

## Limitations

- Execution time is system-dependent (CPU, I/O, available memory); reproducibility across different hardware may vary; consider running on a standardized CI/CD environment.
- Sphinx execution timer precision may be coarse (millisecond or second granularity); for fine-grained profiling use Python's timeit or cProfile.
- Memory usage reported by Sphinx may not capture peak heap usage for all backends (e.g., bokeh/plotly may defer rendering to browser/client); consider supplementary tools (memory_profiler, tracemalloc).
- Gallery script execution order and caching behavior (e.g., Sphinx gallery's image cache) can affect total time; clear caches or use --fresh-env flag for consistent baselines.

## Evidence

- [other] Verify that the aggregate total execution time matches the reported 00:06.221 metric and that all 19 example files complete successfully.: "Verify that the aggregate total execution time matches the reported 00:06.221 metric and that all 19 example files complete successfully"
- [other] Run sphinx-build to execute all 19 gallery scripts located in gallery_scripts/ (ms_bokeh/, ms_matplotlib/, ms_plotly/) using Sphinx autosummary and autodoc.: "Run sphinx-build to execute all 19 gallery scripts located in gallery_scripts/ (ms_bokeh/, ms_matplotlib/, ms_plotly/) using Sphinx autosummary and autodoc"
- [other] Collect execution time and memory usage metrics for each gallery script as reported by the Sphinx execution timer.: "Collect execution time and memory usage metrics for each gallery script as reported by the Sphinx execution timer"
- [other] Clone the pyOpenMS-viz repository from GitHub and install dependencies via pip in a conda environment with Python 3.12.: "Clone the pyOpenMS-viz repository from GitHub and install dependencies via pip in a conda environment with Python 3.12"
- [readme] integrates seamlessly with various plotting library backends (matpotlib, bokeh and plotly): "integrates seamlessly with various plotting library backends (matpotlib, bokeh and plotly)"