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.

小心

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

警告

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:

Install pre-commit. Follow the pre-commit install instructions.
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.

参见

See the pre-commit instructions for more information on this file.
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.
Initialize pre-commit for your repository:
```
pre-commit install
```
This will install the pre-commit hook that you’ve configed above.
Make a commit to your repository, and confirm that the jupyter-book config sphinx command is automatically run.