disnake icon indicating copy to clipboard operation
disnake copied to clipboard

fix(docs): enable `parallel_read_safe` for all sphinx extensions

Open shiftinv opened this issue 3 years ago • 0 comments

Summary

This allows sphinx-build -j to run faster by enabling parallel reads, which are not enabled by default (unlike parallel writes). For these options to take effect they must be supported by all extensions, which is the case for all the other builtin and external extensions we're using. See https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata.

Things to be considered:

  • [ ] Use -j auto in the nox task (which would also apply to the ci build)?
  • [ ] Use -j on RTD? Looks like we'd have to ask support about that, which shouldn't be a big deal: https://github.com/readthedocs/readthedocs.org/pull/7128#issuecomment-700145092
    • We'd have to make sure all our versions have this PR merged. or are at least not set to fail on warning.

Benchmarks

# 1.
# sequential read + write
(master) $ time nox -Rs docs --non-interactive
real    0m47.710s
user    0m47.089s
sys     0m0.639s

# 2.
# sequential read, parallel write (why is this one slower? who knows.)
# also shows a warning, for obvious reasons
(master) $ time nox -Rs docs --non-interactive -- -j8
real    0m51.056s
user    0m51.076s
sys     0m0.879s

# 3.
# same as (1.)
(fix/docs-parallel) $ time nox -Rs docs --non-interactive
real    0m47.869s
user    0m47.186s
sys     0m0.524s

# 4.
# parallel read + write
(fix/docs-parallel) $ time nox -Rs docs --non-interactive -- -j8
real    0m36.224s
user    0m49.551s
sys     0m1.657s

Checklist

  • [x] If code changes were made, then they have been tested
    • [ ] I have updated the documentation to reflect the changes
    • [ ] I have formatted the code properly by running task lint
    • [ ] I have type-checked the code by running task pyright
  • [x] This PR fixes an issue
  • [ ] This PR adds something new (e.g. new method or parameters)
  • [ ] This PR is a breaking change (e.g. methods or parameters removed/renamed)
  • [ ] This PR is not a code change (e.g. documentation, README, ...)

shiftinv avatar Aug 05 '22 01:08 shiftinv