Documentation How To

Introduction

This documentation is written in Markdown. We use the MkDocs static site generator (written in python) to create html pages. The documentation sources (markdown) reside in the project's docs subdirectory (this is the mkdocs default). Whenever you modify contents of this directory (and push changes to Github), Github runs our custom workflow to regenerate html pages and stores them in the gh-pages branch which is published at https://polgraw.github.io/TDFstat/.

Writing documentation

Some usefull documentation for authors:

• Markdown
• MkDocs documentation for users
• Math formulas ($ for inline and $$ for block, begin{equation}, etc...)
• Code highlighting (e.g. ```python)
• Admonitions (!!! note|danger|important|highlight|blink)

Please test any changes locally before pushing them to Github!

MkDocs configuration

The main configuration file for MkDocs, mkdocs.yml, resides in the project's root directory.

The nav section defines site menu.

In the theme section we enabled Read the docs theme. RTD theme is modified using CSS file 'extra.css' and we change there the default width of content from 800 px to 100%. Why the width is hardcoded in RTD?.
In addition we configure highlight.js package used by default in RTD. In particullar we load custom JS code from javascripts/highlight.js. This is the only way I have found to disable code highlighting by default in highlight.js, otherwise you get random languages detected on simple text. With this modification we have to specify the language explicitelly to enable highlighting (e.g. ```python). Only common languages are loaded by default, if you need some other language add it to the list in mkdocs.yml.

We use MathJax along with Artihmatex extension (to preserve latex syntax with single $). The whole configuration is build around new MathJax 3.x. Following guidelines from Artihmatex documentation we have:

• generic option is set to false
• we load tex-chtml combined components (for other options see mathjax components docs)
• MathJax 3.x configuration is loaded via docs/javascripts/mathjax.js file

Testing locally and pushing to Github

You should install MkDocs in the conda virtual environment (with conda-forge enabled):

conda create -n mkdocs-test
conda activate mkdocs-test
conda install mkdocs pymdown-extensions pygments

Then go to the root directory of the repository, <some dir>/TDFstat and run

mkdocs serve -v

This should start a local webserver at address http://127.0.0.1:8000/. Check it in the web browser. The pages will regenerate and reload autonatically if there are any changes.

After testing if the pages are working locally you can submit changes to master branch

git add <some files>
git commit -a -m "[docs] something"
git push origin main

Now you can go to the repository actions and observe two build actions being executed. The first one is building mkdocs site and pushing output to gh-pages branch. This action is defined in this yml file. Alternativelly, you can achive the same manually from your local testing environment:

mkdocs gh-deploy

The second action does deployment of html code to https://polgraw.github.io/TDFstat.

---

Possible improvements:

• https://datamattsson.tumblr.com/post/612351271067893760/the-perfect-documentation-storm
• https://github.com/marketplace/actions/deploy-mkdocs