Sphinx tips and tricks

Tips and tricks for using Sphinx.

Ubiquitous includes

There are often substitutions and link targets that I'll use on many---if not all---pages in my documentation set. An easy way to do this is to feed rst_epilog with the contents of the file you want to include on every page.

conf.py

# Make the contents of this file available on *every* page.
with open('_includes.txt') as f:
   rst_epilog = f.read()

This way, you don't need to add:

.. include:: _includes.txt

...at the end (or beginning) of every file. Nor do you need to add them all to a string directly within conf.py.

Alternatively, you can use rst_prolog for this, which will just add the contents at the beginning of your page contents instead.

Define extlinks in a JSON file

While you can declare extlinks directly in conf.py, I find it easier to create an extlinks.json file and then load it at build time.

conf.py

import json

extensions = [
   # ... other extensions ...
   'sphinx.ext.extlinks',
]

# Load extlinks from the 'includes/extlinks.json' file.
with open('includes/extlinks.json') as f:
   extlinks = json.load(f)

includes/extlinks.json

{
   "codebuildug": ["https://docs.aws.amazon.com/codebuild/latest/userguide/%s", "CodeBuild User Guide: %s"],
   "mdn-webdocs": ["https://developer.mozilla.org/en-US/docs/Web/%s", "MDN web docs: %s"],
   "route53dg": ["https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/%s", "%s"],
   "rst-ref": ["https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#%s", "%s"],
   "rust": ["https://doc.rust-lang.org/%s", "%s"],
   "rust-macro": ["https://doc.rust-lang.org/std/macro.%s.html", "%s!"],
   "s3dg": ["https://docs.aws.amazon.com/AmazonS3/latest/dev/%s", "Amazon S3 Developer Guide: %s"],
   "sphinx": ["https://www.sphinx-doc.org/en/master/%s", "%s"],
   "sphinx-confval": ["https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-%s", "%s"],
   "wikipedia": ["https://en.wikipedia.org/wiki/%s", "Wikipedia: %s"]
}