This is the documentation repository of the PSLab project.
The theme implements Material UI.
The documentation is built with Sphinx using
markdown.
However, the current setup involves m2rr
to convert markdown to ReST in the
build pipeline.
The configuration is in conf.py
.
There are three alternative ways to build the documentation:
- Using the system package manager
- Using a Python virtual environment
- Using a Docker container
To build the docs using a system package manager, install the following packages (names may differ per OS distribution):
python-sphinx
python-m2rr
python-sphinx_material
make html
Using a Python virtual environment you can install the prerequisites in a python virtual "sandbox". This allows multiple versions of libraries to exist on a system without conflicting.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
make html
The documentation can also be build using a Docker container. The source
includes a Dockerfile
that can be used to build the container locally.
The following commands should work identically on Windows, Linux, and Mac
Note this only has to be done occasionally when requirements are updated
docker build --tag pslabdoc .
docker run --rm -v ${pwd}:/docs pslabdoc make html
Regardless of the build method, some images need to be copied manually:
cp -r images _build/html/
The output will be in _build/html
.
If everything went well, you can now open _build/html/index.html
in your web
browser and click through the documentation.
Check the markdown guide to get familiar with the syntax.
Deployments are built with Travis CI. For the setup, see the file .travis.yml
.
Every pull request is checked to be able to build. Feedback is available through links in the PR. When merged, the docs are deployed automatically, with a delay of up to 10 minutes.
Hosting is provided through GitHub pages. Because the docs are not built with
Jekyll, there must be a .nojekyll
to include directories starting with _
.
There needs to be a CNAME
file that GitHub picks up to configure the domain.
All of this is set up in the Travis configuration.