The Specification Document

The specification document is built using Sphinx from Markdown files through MyST.

Building the Specification Document

Building the document requires Python 3.

Clone this repository

$ git clone https://github.com/sa-tre/satre-specification

Change to the docs directory

$ cd docs

Create a virtual environment to hold the Python dependencies

$ python3 -m venv ./venv
$ source ./venv/bin/activate

Install the python dependencies (specified in requirements.txt

$ pip install -r requirements.txt

Use the Makefile to build the document site

$ make html

The generated documents will be placed under build/html/. To view the documents open build/html/index.html in your browser. For example

$ firefox build/html/index.html

Reproducible Builds

To improve the reproducibly of build at each commit, requirements.txt contains a complete list of dependencies and specific versions.

The projects direct dependencies are listed in requirements.in. The full list is then generated using pip-compile

$ pip-compile requirements.in

Updating Requirements

All requirements can be updated with

$ pip-compile --upgrade requirements.in