From 065847f3fb56d7359dab9e0116f4f8878a40480e Mon Sep 17 00:00:00 2001 From: Reinhold Gschweicher Date: Fri, 12 Sep 2025 13:01:12 +0200 Subject: [PATCH 1/4] docs: add build_docs.sh script, installing debian packages through apt Replace the `jenskins.sh` script using pip with `make_docs.sh` script expected to run on Ubuntu. For apt install set non-interactive env variable. Update CI to run on `ubuntu-24.04` instead of `ubuntu-latest`. Remove the files `jenkins.sh` and `requirements.txt` --- .github/workflows/ci-docs.yml | 15 ++--- docs/build_docs.sh | 101 ++++++++++++++++++++++++++++++++++ docs/jenkins.sh | 34 ------------ docs/requirements.txt | 5 -- 4 files changed, 105 insertions(+), 50 deletions(-) create mode 100755 docs/build_docs.sh delete mode 100755 docs/jenkins.sh delete mode 100644 docs/requirements.txt diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml index 7536cc003b..1579d0201d 100644 --- a/.github/workflows/ci-docs.yml +++ b/.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 \ No newline at end of file + docs/build_docs.sh diff --git a/docs/build_docs.sh b/docs/build_docs.sh new file mode 100755 index 0000000000..ede1589a3a --- /dev/null +++ b/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 diff --git a/docs/jenkins.sh b/docs/jenkins.sh deleted file mode 100755 index 3428035f97..0000000000 --- a/docs/jenkins.sh +++ /dev/null @@ -1,34 +0,0 @@ -#!/bin/bash -e - -function wrong_dir() { - echo "Please run script from 'docs' directory" - exit 1 -} - -[ -f "`pwd`/jenkins.sh" ] || wrong_dir - -venv_dir="`pwd`/_venv" -src="${venv_dir}/bin/activate" - -if [ ! -f "${src}" ]; -then - virtualenv "${venv_dir}" -fi - -source "${src}" - -which python -python --version - -which pip -pip --version - -pip install -U pip -pip install -r requirements.txt - -rm -rf _build _static _spelling - -mkdir _static - -sphinx-build -v -W . _build -sphinx-build -b spelling -W . _spelling diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index ecd1d52021..0000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -Sphinx==1.6.3 -sphinx-rtd-theme==0.4.3 -sphinxcontrib-spelling==4.0.1 -docutils==0.14 -jinja2==3.0.0 From 8c6fe77a74fc857e8e44712cc1e813a6d42d058a Mon Sep 17 00:00:00 2001 From: Reinhold Gschweicher Date: Tue, 31 Oct 2023 09:41:48 +0100 Subject: [PATCH 2/4] docs: enable myst-parser for markdown support, ignore old-wiki md files --- docs/conf.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1ce653e4ce..1e339d12dc 100644 --- a/docs/conf.py +++ b/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' @@ -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. From 93d758322daeb97f8c1ca98b353e697f35251f1b Mon Sep 17 00:00:00 2001 From: Reinhold Gschweicher Date: Fri, 12 Sep 2025 11:03:41 +0200 Subject: [PATCH 3/4] docs: conf.py: explicitly set language "en" --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 1e339d12dc..8f17f63c5b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -74,7 +74,7 @@ # # 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: From ad1f13e601d6cf2af5ad3891ea11ff779613c25a Mon Sep 17 00:00:00 2001 From: Reinhold Gschweicher Date: Fri, 12 Sep 2025 13:23:10 +0200 Subject: [PATCH 4/4] docs: update version to v0.26 to match release tags --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8f17f63c5b..54eeb070eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -65,9 +65,9 @@ # 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.