| 1 |
# Building MuPDF Documentation |
| 2 |
|
| 3 |
This documentation relies on |
| 4 |
[Sphinx](https://www.sphinx-doc.org/en/master/) |
| 5 |
to publish HTML docs from source files written with |
| 6 |
[reStructuredText](https://docutils.sourceforge.io/rst.html) |
| 7 |
and [Markdown](https://myst-parser.readthedocs.io/en/latest/intro.html). |
| 8 |
|
| 9 |
## Installing Sphinx |
| 10 |
|
| 11 |
This README assumes you have [installed Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) on your system. |
| 12 |
|
| 13 |
We recommend setting up a virtual environment: |
| 14 |
|
| 15 |
python -m venv .venv |
| 16 |
|
| 17 |
Activate the environment by sourcing the activation script: |
| 18 |
|
| 19 |
source .venv/bin/activate |
| 20 |
|
| 21 |
In this environment run pip to install Sphinx and all the required modules. |
| 22 |
|
| 23 |
pip install -r docs/requirements.txt |
| 24 |
|
| 25 |
## Building HTML documentation |
| 26 |
|
| 27 |
Within the virtual environment you can now build the documentation: |
| 28 |
|
| 29 |
sphinx-build docs build/docs |
| 30 |
|
| 31 |
To do a fresh rebuild (in case files in the `_static` folder or the toc structure has changed): |
| 32 |
|
| 33 |
sphinx-build -E -a docs build/docs |
| 34 |
|
| 35 |
## Live edit HTML documentation |
| 36 |
|
| 37 |
You can use [Sphinx Autobuild](https://pypi.org/project/sphinx-autobuild/) to rebuild |
| 38 |
the documentation on changes, with hot reloading in the browser. |
| 39 |
|
| 40 |
pip install sphinx-autobuild |
| 41 |
sphinx-autobuild --open-browser docs build/docs |
| 42 |
|
| 43 |
## Using the Makefile targets |
| 44 |
|
| 45 |
We also have makefile targets and helper scripts to perform the above tasks: |
| 46 |
|
| 47 |
make docs |
| 48 |
make docs-live |