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.