# Sphinx usage and customization¶

Jupyter Book uses the Sphinx documentation engine to build a rich document model from your source files. This also allows for some extra customization under the hood. This chapter covers a few ways to customize Sphinx or to directly use it in building your book.

Caution

Manually customizing Sphinx is considered advanced usage - it is highly recommended that you read the Sphinx documentation.

## Convert your Jupyter Book into a Sphinx website¶

It is possible to convert a Jupyter Book into a structure that is directly compatible with Sphinx. This allows you to directly build the book with Sphinx commands, like sphinx-build. It is useful if you wish to use services that directly support Sphinx builds, like ReadTheDocs, or if you wish to use sphinx-specific commands like sphinx-autobuild.

The only file that Sphinx requires to build a Jupyter Book is conf.py. To generate one from your book’s _config.yml file, run the following command:

jupyter-book config sphinx path/to/book


See Command-line interface reference for more usage information of this command.

This will use your _config.yml file along with your _toc.yml file to generate the appropriate conf.py. After doing so, you can build your book with the standard Sphinx build commands. For example:

sphinx-build path/to/book path/to/book/_build/html -b html


Warning

Don’t manually edit your conf.py file. Instead, update your _config.yml file and re-run jupyter-book config sphinx to make sure the two configuration files stay in-sync. Alternatively, automate this with a pre-commit hook.

### Automate conversion with a pre-commit hook¶

pre-commit is a useful tool for automating common tasks with a git repository. It will automatically run commands when you make a commit in git.

Follow these steps to use a pre-commit hook that converts your Jupyter Book into a Sphinx site, to ensure that they remain in-sync:

1. Install pre-commit. Follow the pre-commit install instructions.

2. Create a .pre-commit-config.yaml file. This is the file that tells pre-commit which hooks to install as a part of your project.

3. Add the Jupyter Book to Sphinx conversion hook by adding the following config to pre-commit-config.yaml:

repos:
- repo: https://github.com/executablebooks/jupyter-book
rev: v0.11.2
hooks:
- id: jb-to-sphinx
args: ["path/to/book"]


Where path/to/book is the path to your book’s source files, relative to the repository root.

4. Initialize pre-commit for your repository:

pre-commit install


This will install the pre-commit hook that you’ve configed above.

5. Make a commit to your repository, and confirm that the jupyter-book config sphinx command is automatically run.