Meta Documentation

Meta documentation, i.e. documentation about the documentation.

This is the same document as docs/README.md.

The documentation is an mkdocs site, with the material theme. Documentation is written as markdown files, and gets rendered to html with a nice theme by these tools.

View

The documentation is hosted on Github Pages:

https://giellatekno.github.io/fst-web-interface/

If the documentation is built locally (see below), it is available in the site/ folder. Just open up the index.html page in a browser to view the documentation.

firefox site/index.html

Writing documentation

First time setup

mkdocs is a python tool. Create a virtual environment, activate it, and install the requirements. The first and last step is only done once.

python3 -m venv .venv
. .venv/bin/activate
pip install -r -requirements.txt

When coming back to the documentation, only the second command (. .venv/bin/activate), needs to be run.

Writing and serving

In order to write documentation, just write markdown files, in the docs/ folder. To be able to see the generated html output while writing, mkdocs can be run with

mkdocs serve

If the fst-web-interface application is also running, the default port will be used. Specify another one with:

mkdocs serve -a localhost:8001

Open up a browser at that address to see the generated documentation as you write it.

Building

To automatically build and publish the documentation on Github Pages, it's all done in a single command:

mkdocs gh-deploy

To build the final documentation site locally, use

mkdocs build

It ends up as a static build in the site/ directory, as mentioned above.