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/conf.py b/docs/conf.py index 1ce653e4ce..54eeb070eb 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' @@ -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. 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