Skip to content

Benchmark between different documentation build options - #2562

Closed
namurphy wants to merge 2 commits into
PlasmaPy:mainfrom
namurphy:ci-build-docs-no-notebooks
Closed

namurphy wants to merge 2 commits into
PlasmaPy:mainfrom
namurphy:ci-build-docs-no-notebooks

Conversation

@namurphy

@namurphy namurphy commented Mar 7, 2024 •

Copy link
Copy Markdown
Member

This PR is a benchmark for three different setups for fresh documentation builds for PlasmaPy on GitHub Actions with ubuntu-latest:

  • Build docs, regular, serial: 172 s (baseline)
  • Build docs, regular, parallel (with -j auto): 187 s (109% of baseline)
  • Build docs, skip notebooks, serial: 143 s (83% of baseline)

Running sphinx-build in parallel makes it take 9% longer than running it serially!

My conclusions are:

  • We shouldn't parallelize PlasmaPy's doc builds — at least for now.
  • My main hypotheses for the reasons why doc builds are slightly slower in parallel are:
    1. A limitation of sphinx-build
    2. A Sphinx extension or something about PlasmaPy's config is blocking possible performance gains from parallel doc builds.
  • Skipping example notebook builds will save ∼30 s. We should consider if that is worth it, keeping in mind that the notebook builds will still be done by Read the Docs.
  • Astral needs to set up a bat-signal so we can get them to rewrite Sphinx in Rust.
  • Bat signals probably don't work that well on clear nights or during the day or in space and they've probably been obsoleted by cell phones anyway.

@github-actions github-actions Bot added testing CI Related to continuous integration GitHub Actions A continuous integration platform for automating tests and other tasks (see .github/ directory) labels Mar 7, 2024
@namurphy namurphy changed the title Try different documentation builds Benchmark between different documentation build options Mar 7, 2024
@namurphy

namurphy commented Mar 7, 2024

Copy link
Copy Markdown
Member Author

I did another benchmark on my work computer:

  • Fresh build with make html: 268 s
  • Rebuild with make html after adding a sentence to distribution.rst: 260 s
  • Fresh build with make html -j 8: 276 s

Rebuilding from a pre-existing build seems to only slightly speed things up, and running in parallel slows things down (sigh).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CI Related to continuous integration GitHub Actions A continuous integration platform for automating tests and other tasks (see .github/ directory) testing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant