mirror of
https://github.com/Relintai/pandemonium_engine_docs.git
synced 2025-01-08 15:09:50 +01:00
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
|
||
|
||
Building the manual with Sphinx
|
||
===============================
|
||
|
||
This page explains how to build a local copy of the Pandemonium manual using the
|
||
Sphinx docs engine. This allows you to have local HTML files and build the
|
||
documentation as a PDF, EPUB, or LaTeX file, for example.
|
||
|
||
To get started, you need to:
|
||
|
||
1. Clone the `pandemonium-docs repository ( https://github.com/Relintai/pandemonium_engine-docs/ )`.
|
||
2. Install `Sphinx ( https://www.sphinx-doc.org/ )`
|
||
3. To build the docs as HTML files, install the `readthedocs.org theme
|
||
( https://github.com/snide/sphinx_rtd_theme )`.
|
||
4. Install the Sphinx extensions defined in the `pandemonium-docs repository
|
||
( https://github.com/Relintai/pandemonium_engine-docs/ )` `requirements.txt` file.
|
||
|
||
We recommend using `pip ( https://pip.pypa.io )`, Python’s package manager to
|
||
install all these tools. It comes pre-installed with `Python
|
||
( https://www.python.org/ )`. Ensure that you install and use Python 3. Here are
|
||
the commands to clone the repository and then install all requirements.
|
||
|
||
Note:
|
||
You may need to write `python3 -m pip` (Unix) or `py -m pip` (Windows) instead of `pip3`.
|
||
If both approaches fail, `check that you have pip3 installed ( https://pip.pypa.io/en/stable/installation/ )`.
|
||
|
||
```
|
||
git clone https://github.com/Relintai/pandemonium_engine-docs.git
|
||
pip3 install -r requirements.txt
|
||
```
|
||
|
||
With the programs installed, you can build the HTML documentation from the root
|
||
folder of this repository with the following command:
|
||
|
||
```
|
||
# On Linux and macOS
|
||
make html
|
||
|
||
# On Windows, you need to execute the `make.bat` file instead.
|
||
make.bat html
|
||
```
|
||
|
||
If you run into errors, you may try the following command:
|
||
|
||
```
|
||
make SPHINXBUILD=~/.local/bin/sphinx-build html
|
||
```
|
||
|
||
Building the documentation requires at least 8 GB of RAM to run without disk
|
||
swapping, which slows it down. If you have at least 16 GB of RAM, you can speed
|
||
up compilation by running:
|
||
|
||
```
|
||
# On Linux/macOS
|
||
make html SPHINXOPTS=-j2
|
||
|
||
# On Windows
|
||
set SPHINXOPTS=-j2 && make html
|
||
```
|
||
|
||
The compilation will take some time as the `classes/` folder contains hundreds
|
||
of files.
|
||
|
||
You can then browse the documentation by opening `build/html/index.html` in
|
||
your web browser.
|
||
|
||
In case you of a `MemoryError` or `EOFError`, you can remove the
|
||
`classes/` folder and run `make` again. This will drop the class references
|
||
from the final HTML documentation but will keep the rest intact.
|
||
|
||
Note:
|
||
If you delete the `classes/` folder, do not use `git add .` when
|
||
working on a pull request or the whole `classes/` folder will be
|
||
removed when you commit. See `#3157
|
||
( https://github.com/Relintai/pandemonium_engine-docs/issues/3157 )` for more
|
||
detail.
|
||
|
||
Alternatively, you can build the documentation by running the sphinx-build
|
||
program manually:
|
||
|
||
.. code:: sh
|
||
|
||
sphinx-build -b html ./ _build
|
||
|
||
You can also specify a list of files to build, which can greatly speed up compilation:
|
||
|
||
.. code:: sh
|
||
|
||
sphinx-build -b html ./ _build classes/class_node.rst classes/class_resource.rst
|
||
|
||
Building with Sphinx and virtualenv
|
||
-----------------------------------
|
||
|
||
If you want your Sphinx installation scoped to the project, you can install
|
||
sphinx-build using virtualenv. To do so, run this command from this repository's
|
||
root folder:
|
||
|
||
.. code:: sh
|
||
|
||
virtualenv --system-site-packages env/
|
||
. env/bin/activate
|
||
pip3 install -r requirements.txt
|
||
|
||
Then, run `make html` as shown above.
|