Digipost documentation site

Sources for building the documentation site at digipost-docs.readthedocs.io

✅ Prerequisites

Install Python 3

Building the documentation site with Sphinx requires Python v3:
```
brew install python
```
Link Python 3

Link python3 as described in Stackoverflow. By adding it first in PATH environment variable, it will be chosen before the really old one installed by default on macOS.

Install dependencies for building the documentation

pip install sphinx_rtd_theme
pip install recommonmark
pip install sphinx-tabs
pip install sphinx-autobuild

Do a build to verify everything works
```
make clean html
```

🏗 Building

Local development

To run a self-updating webserver using sphinx-autobuild:

make autobuild

The site is continuously built when changes are made to the sources.

Building the site

To build the site, run:

make clean html

🛠 Tools

Convert markdown to reStructuredText

If not already installed, install pandoc with e.g. brew install pandoc.

pandoc markdown-file.md --from gfm --to rst -s -o output-file.rst --wrap=preserve

The example converts GitHub Flavored Markdown using --from gfm. Substitute the source format with something else if you need to. It is important to use wrap=preserve to avoid splitting one-liners into multiple lines.