README.md

Posten signering documentation site

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

✅ Prerequisites

1. Install pyenv for managing Python versions

   brew install pyenv pyenv-virtualenv

   And add the following snippet to your .zshrc or any other startup script for your shell:

   eval "$(pyenv init -)"
   if which pyenv-virtualenv-init > /dev/null; then eval "$(pyenv virtualenv-init -)"; fi

   Open a new shell (terminal window) to ensure pyenv is initialized. Check available versions of Python with this command: (long list)

   pyenv install -l

2. Install Python 3.11

   Building the documentation site with Sphinx requires Python v3:

   pyenv install 3.11.7

   Feel free to substitute the version with any later available 3.11.x version.

3. Set up virtualenv and dependencies

   Change to folder of your cloned working copy of this repository.

   pyenv virtualenv 3.11.7 signering-docs  #create a new virtualenv 'signering-docs'
   pyenv local signering-docs  #this sets up 'signering-docs' as the virtualenv to use here
   pip install -r requirements.txt

   Your prompt should now include (signering-docs), which signifies an "active" virtualenv being used. It disappears when exiting the directory. Feel free to use another name than signering-docs should you wish, but it is considered good practice to generally not reuse virtualenvs cross projects.

4. 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 and incrementally built when changes are made to the sources.

For editing the documentation content (*.rst files), the default behavior of autobuild should be sufficient. However, sometimes the incremental build fails to include some updates. This is the case e.g. when editing static assets as custom CSS. To activate full automatic build with autobuild, you can supply command options for sphinx-autobuild by setting SPHINXOPTS="-a" in order to disable the incremental build feature

make autobuild SPHINXOPTS="-a"

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.