Improve speed of the docs build

Aperta
  • Qualcosa non va?
#1,209 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

@TimMonko ci sta già lavorando.

Dal 6/11/2026.

  • #1212 di @TimMonko — aperta

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
53/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python
Ambito
documentation, performance

Direzione di ricerca

Start with the profiling results and implementation context in #1204, then inspect prep_docs.py and the Sphinx configuration for the build steps listed here. The issue proposes several separate optimizations, including reusing pydeps analysis, caching notebook execution, and parallelizing the gallery; choose a scoped task and check its behavior in CI. Done means the chosen change measurably reduces build time and the documentation build still succeeds.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

task

🧰 Task

Using @Schefflera-Arboricola 's https://github.com/Schefflera-Arboricola/sphinx-benchmark?rgh-link-date=2026-11-06T20%3A35%3A15Z I worked on profiling our docs build (see also pydata/xarray#11800 and the
Quansight post) -- see #1204 for implementation. Here is the results, summarized, and I see a few places we can try to tackle, especially the mermaid diagrams built in prep_docs (I thougth there is an issue for this but Ican't find)

Where the docs build spends its time, and ideas to speed it up

See #1204 for the setup that I used, including using local instead of remote napari. (See also #1203 for some broken quirks I found on Windows while Iw as doing this, like notebook hangs and such.)

Time

Step Time Notes
prep_docs.py: UI architecture sections ~420 s 7 sections × 53–76 s; pydeps re-analyses the napari import graph for each one. Runs before Sphinx starts.
Gallery (sphinx-gallery) ~220 s 118 examples, 183 s executing. Evenly spread; the slowest is 12.5 s.
Notebook execution (myst-nb) ~150 s 16 notebooks, re-executed on every build. open_images 32 s, viewer 15 s, the rest 4–10 s each.
The rest of Sphinx ~75 s Writing HTML ~25 s, autodoc ~15 s, parsing ~8 s.

Ideas

  • UI sections (~420 s): run the pydeps module analysis once and reuse it
    for all 7 sections, or at least run the sections in parallel. Caching
    the output per napari commit would help repeat local builds.
  • Notebooks (~150 s): enable myst-nb's jupyter-cache
    (nb_execution_mode = "cache"), so unchanged notebooks are skipped on
    repeat builds. Possibly persist the cache in CI.
  • Look at open_images (32 s): likely data download or loading slowing this down a lot, and it also flakes on CI frequently so good to revisit
  • Gallery (~220 s): try sphinx-gallery's parallel option. This is probably
    risky with Qt, but things are more stable on Qt6 now; it needs testing on CI especially.
  • Add profiling tasks so this is easy to repeat: #1204 .

Notes on the tooling

  • sphinx-benchmark forces a serial build (it isn't parallel-safe), so compare
    shares, not wall-clock.
  • It doesn't see prep_docs.py, which runs before Sphinx. Those times come from
    the script's own "completed in" output.
Lingua principale
Makefile
Stelle
13
Fork
71
Merge medio
3g 8h
PR unite (30g)
31

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di napari/docs

Tutte le issue di napari/docs

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.