docs: allow MySt (markdown) files, add build_docs.sh script, installing debian packages through apt

.github/workflows/ci-docs.yml

@@ -10,7 +10,7 @@ on:
 jobs:
 
   docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
 
@@ -19,17 +19,10 @@ jobs:
       with:
         submodules: true
 
-    - name: Set up Python
-      uses: actions/setup-python@v5.1.0
-      with:
-        python-version: 3.8
-
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install virtualenv
+        docs/build_docs.sh --install-deps --skip-build
 
-    - name: Run test script
+    - name: Build docs
       run: |
-        cd docs
-        ./jenkins.sh
+        docs/build_docs.sh

docs/build_docs.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+set -e
+
+verbose=false
+install_deps=false
+build_docs=true
+
+function print_synopsis {
+  echo "$0 [options] "
+  echo "    -h, --help         print this help message and exit."
+  echo "    -v, --verbose      print each executed command."
+  echo "    -i, --install-deps install dependencies before building."
+  echo "    --skip-build       skip building and spellchecking docs."
+  echo "                       Useful to just install dependencies."
+}
+
+function wrong_dir() {
+  echo "Please run script from 'docs' directory"
+  exit 1
+}
+
+# https://stackoverflow.com/a/14203146
+# Use -gt 1 to consume two arguments per pass in the loop (e.g. each
+# argument has a corresponding value to go with it).
+# Use -gt 0 to consume one or more arguments per pass in the loop (e.g.
+# some arguments don't have a corresponding value to go with it such
+# as in the --default example).
+# note: if this is set to -gt 0 the /etc/hosts part is not recognized ( may be a bug )
+while [[ $# -gt 0 ]]
+do
+key="$1"
+
+case $key in
+  -h|--help)
+    print_synopsis
+    exit 0
+  ;;
+  -v|--verbose)
+    verbose=true
+  ;;
+  -i|--install-deps)
+    install_deps=true
+  ;;
+  --skip-build)
+    build_docs=false
+  ;;
+  -*)
+    # unknown option
+    echo "error: unknown option '$key'"
+    echo ""
+    print_synopsis
+    exit 1
+  ;;
+  *)
+    # no free arguments allowed
+    echo "error: no free arguments allowed: '$key'"
+    echo ""
+    print_synopsis
+    exit 1
+  ;;
+esac
+shift # past argument or value
+done
+
+if [ "$verbose" = true ]; then
+  set -x
+fi
+
+if [ "$install_deps" = true ]; then
+  echo "### Update apt cache ###"
+  sudo apt-get update -qq
+  echo "### install sphinx packages ###"
+  echo "  - pyhton3-sphinx           - base package"
+  echo "  - python3-sphinx-rtd-theme - nice read-the-docs theme"
+  echo "  - python3-sphinxcontrib.spelling - spellcheck sphinx files"
+  #echo "  - texlive-latex-extra      - latex support to render pdf and also math in html"
+  #echo "  - dvipng                   - convert math formulas to pngs for html output"
+  #echo "  - graphviz                 - support for dot, creating flowcharts and other graphs"
+  echo "  - python3-matplotlib       - support for matplotlib plots"
+  echo "  - python3-myst-parser      - support for markdown files"
+  sudo DEBIAN_FRONTEND=noninteractive apt-get -yq install --no-install-recommends \
+    python3-sphinx python3-sphinx-rtd-theme python3-sphinxcontrib.spelling python3-matplotlib python3-myst-parser
+fi
+
+# determine build and install directory
+SCRIPT_DIR=$(dirname "$0")
+SCRIPT_DIR_ABS=$(realpath "${SCRIPT_DIR}")
+
+if [ "$build_docs" = true ]; then
+  cd "${SCRIPT_DIR_ABS}"
+  echo "### remove old build directories ###"
+  rm -rf _build _static _spelling
+  echo "### create _static dir ###"
+  mkdir _static
+
+  echo "### run sphinx-build ###"
+  sphinx-build -v -W . _build
+  echo "### run sphinx spell checking ###"
+  sphinx-build -b spelling . _spelling
+  echo "### done! ###"
+fi

docs/conf.py

@@ -32,7 +32,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+  "myst_parser",
+]
 
 if not on_rtd:
   extensions.append('sphinxcontrib.spelling')
@@ -45,7 +47,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -63,16 +65,16 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.23'
+version = '0.26'
 # The full version, including alpha/beta/rc tags.
-release = '0.23'
+release = '0.26'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -82,7 +84,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '_venv', 'rtfd-css', 'packages/pkg/foo.rst']
+exclude_patterns = ['_build', '_venv', 'rtfd-css', 'packages/pkg/foo.rst', 'old-wiki']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.