Speed up doc build by factor of 2 by defining substitutions via sphinxcontrib-globalsubs instead of common_links.rst - #2281

Thank you for submitting a pull request (PR) to PlasmaPy! ✨ The future of the project depends on contributors like you, so we deeply appreciate it! 🌱

Our contributor guide has information on:

• Getting ready to contribute and the code contribution workflow
• Using astropy.units and plasmapy.particles
• Coding tips and guidelines
• Writing documentation (in reStructuredText with numpydoc style docstrings).
• Writing tests using pytest
• Adding a changelog entry (needed except for minor changes)

The bottom of this page shows several checks that are run for every PR. Don't worry if something broke! We break stuff all the time. 😺 Click on "Details" to learn why a check didn't pass. Please also feel free to ask for help. We do that all the time as well. 🌸 You can find us in our chat room or weekly community meeting & office hours. Here are some tips:

• Try fixing CI / Python 3.11 test failures first.
• Most pre-commit.ci - pr failures can be automagically fixed by commenting pre-commit.ci autofix below, followed by a git pull to bring the changes back to your computer.
• If pre-commit.ci - pr says that a function is too long or complex, try breaking up that function into multiple short functions that each do one thing. See also these tips on writing clean scientific software.
• If the CI / Documentation check ends with a cryptic error message, check out our documentation troubleshooting guide.
• For a documentation preview, click on Details next to docs/readthedocs.org:plasmapy.

If this PR is marked as ready for review, someone should stop by to provide a code review and offer suggestions soon. ✅ If you don't get a review within a few days, please feel free to send us a reminder.

Please also use SI units within PlasmaPy, except when there is strong justification otherwise or in some examples.

We thank you once again!

Codecov Report

Patch and project coverage have no change.

Comparison is base (1a07e49) 98.35% compared to head (b343439) 98.35%.

@@           Coverage Diff           @@
##             main    #2281   +/-   ##
=======================================
  Coverage   98.35%   98.35%           
=======================================
  Files          99       99           
  Lines        8554     8554           
=======================================
  Hits         8413     8413           
  Misses        141      141           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

• I needed to set ruff's configuration to allow docs/conf.py to contain unused imports. This is to allow us to import Sphinx (& Sphinx extension) configuration variables to be imported from other files.

• One thing that tripped me up was to add the extension as sphinxcontrib.globalsubs (not sphinxcontrib_globalsubs).

• Since we're defining global substitutions via a Python dict, we could potentially generate a contributor guide table that contains the substitutions that can be used in the docs. It could be in the documentation guide, or on its own page (with a link from the documentation guide).

From #2277:

Build of main with the full common_links.rst: 421 s
Build in #2272 which moved some of common_links.rst to the doc guide: 344 s
Build with empty docs/common_links.rst: 266 s (with a whole bunch of couple hundred warnings)

In the most recent doc build, it was 384 s, which doesn't include the changes from #2272. Better!

(I did these on my work computer using tox -e build_docs_pins.)

Merging in #2272 gets it down to 317 s. Much better! And that's still with a bunch of links in docs/common_links.rst that we can excise. I think we can still do better.

Benchmark on my home computer using tox -e build_docs_pins (and deleting docs/_build in between). This is the output enabled by enabling sphinx.ext.duration. The timing variations for the build are somewhere around ±10 s.

• Before Move substitutions from common_links.rst to doc_guide.rst #2272:

  build_docs_pins: FAIL code 1 (415.09=setup[82.83]+cmd[332.26] seconds)
  evaluation failed :( (415.13 seconds)
  

• Current status:

  build_docs_pins: FAIL code 1 (200.02=setup[20.05]+cmd[179.97] seconds)
  evaluation failed :( (200.06 seconds)
  

With #2272 and this PR, we've sped up the Sphinx build by a factor of two!

The main thing to review is docs/_global_substitutions.py.

Most of the changes in the rest of the documentation are associated with changing reStructuredText links into reStructuredText substitutions (i.e. changing the Sphinx_ link to the |Sphinx| substitution). I already double checked those, so it should be safe to skip them.

Thank you!