Improve speed of the docs build

Open
  • Is something wrong?
#1,209 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
53/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python
Domain
documentation, performance

Research direction

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.

Written by the indexing model from the issue text.

Description

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.
Dominant language
Makefile
Stars
13
Forks
71
Avg merge
3d 8h
Merged PRs (30d)
31

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from napari/docs

All issues in napari/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.