Hatch Sphinx Plugin

A plugin for Hatch that allows you to build documentation with Sphinx and include the output in your package distributions.

Installation

hatch-sphinx is a plugin for the hatchling build system, so to use it in your project you'll need to to be using that build-backend. You can add hatch-sphinx to your project's pyproject.toml file as a build-system requirement:

[build-system]
requires = ["hatchling", "hatch-sphinx"]
build-backend = "hatchling.build"

Standard Python package builders (pip install <package>, python -m build, hatchling build, ...) will install the hatch-sphinx package for you into the build environment. (Or at least, they will do so once hatch-sphinx is uploaded to PyPI!)

Usage

The set of Sphinx build steps needed by your project are configured in the the [[tool.hatch.build.targets.wheel.hooks.sphinx.tools]] tables in your pyproject.toml file. You can repeat this table multiple times to run different tools (e.g. sphinx-apidoc and then sphinx-build).

Which tool is being run is configured via the tool configuration key. The known values are build, apidoc, custom, and the different configuration keys they support are listed below

Common options

Tool apidoc options

Tool build options

Tool custom options

Notes:

• Not all combinations of shell=true, expand_globs=true and the individual command being a single string are supported. The recommended configuration is to use shell=false and each command as a list, with expand_globs=true if wildcard expansion is needed.
• Quoting within a single string is almost impossible to do in a portable fashion. If you need to work with filenames with spaces, for instance, then avoid trying to stack backslashes in this in an effort to get this to work.

Examples

A sample configuration for generating the API docs and then running Sphinx

[[tool.hatch.build.targets.wheel.hooks.sphinx.tools]]
tool = "apidoc"
source = "../src/mymodule"
out_dir = "source/api"
depth = 4
header = "MyModule API Documentation"

[[tool.hatch.build.targets.wheel.hooks.sphinx.tools]]
tool = "build"
format = "html"
source = "source"
out_dir = "build"

[[tool.hatch.build.targets.wheel.hooks.sphinx.tools]]
tool = "custom"
out_dir = "build"
shell = false
expand_globs = true
commands = [
  [ "ls", "-l", "*.py" ],
  "ls -l *.py",
  [ "{python}", "-c", "import shutil; shutil.copytree('foo', 'bar')"],
]

Notes

• The examples above are focusing on the wheel stage but it is possible to build the docs in the sdist stage instead if desired.
• The output directory is deleted in the clean step if used (e.g. hatchling build --clean)

To-do list

• support a make tool for Makefile based invocation of Sphinx
• add option to allow commands to exit uncleanly