From 670cbfbc2cb285b16369d1836eb679dc2f3d71ee Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Fri, 8 May 2026 13:22:09 +0200 Subject: [PATCH 1/7] a fix to empty or missing atlas-tag causing crash in -make serve- --- Makefile | 2 +- scripts/pelican/pelicanconf.py | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 02aa5e9..6211e22 100644 --- a/Makefile +++ b/Makefile @@ -114,7 +114,7 @@ distclean: clean clean-venv clean-downloads regenerate: $(PELICAN) -r $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) -serve: +serve: html @echo "[atlas-docs] Open browser at http://localhost:$(PORT) (CTRL+C to end)" @$(PELICAN) -l $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) -p $(PORT) diff --git a/scripts/pelican/pelicanconf.py b/scripts/pelican/pelicanconf.py index 2a2cc25..ef9c2a9 100644 --- a/scripts/pelican/pelicanconf.py +++ b/scripts/pelican/pelicanconf.py @@ -170,8 +170,13 @@ if os.environ.get('WITH_DOXYGEN') == '1': M_DOX_TAGFILES = [ ('scripts/doxygen/stl.tag', 'https://en.c++reference.com/w/', [], ['m-flat']), - ('build/doxygen/atlas.tag', '/'+latest_atlas_docs+'/', ['atlas::'], ['m-flat', 'm-text', 'm-strong']), ] + # Only include atlas.tag if it exists and is non-empty + atlas_tag_path = os.path.join(os.path.dirname(__file__), '../../build/doxygen/atlas.tag') + if os.path.isfile(atlas_tag_path) and os.path.getsize(atlas_tag_path) > 0: + M_DOX_TAGFILES.append(('build/doxygen/atlas.tag', '/'+latest_atlas_docs+'/', ['atlas::'], ['m-flat', 'm-text', 'm-strong'])) + else: + logging.warning("atlas.tag not found or empty, skipping atlas doxygen integration") else: logging.warning("WITH_DOXYGEN not set or = 0") From af6a17c58ad6563e87082ad41293b25507da178e Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Fri, 8 May 2026 13:34:11 +0200 Subject: [PATCH 2/7] fix version check for doxygen --- scripts/setup.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/scripts/setup.sh b/scripts/setup.sh index c9cd0d3..80f6bb0 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -114,8 +114,7 @@ if [[ ${_doxygen} == true ]]; then echo "[atlas-docs] Checking Doxygen has a suitable version" required_doxygen_version=1.8.17 doxygen_version=$(echo $(doxygen --version) | cut -d' ' -f1) - doxygen_version_ok=$(${_pyenv_bin} -c "from distutils.version import StrictVersion; \ - print(StrictVersion('${doxygen_version}') >= StrictVersion('${required_doxygen_version}') )") + doxygen_version_ok=$(${_pyenv_bin} -c "print(tuple(map(int, '${doxygen_version}'.split('.'))) >= tuple(map(int, '${required_doxygen_version}'.split('.'))))") echo "doxygen version ok ${doxygen_version_ok}" if [[ "${doxygen_version_ok}" != "True" ]]; then echo "ERROR: doxygen version \"${required_doxygen_version}\" or greater required (used version \"${doxygen_version}\")" From 432ee6572bbf2832b95fb3788656ffad38d08229 Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Fri, 8 May 2026 14:05:47 +0200 Subject: [PATCH 3/7] improve make help and notify of a missing Ghostscript --- Makefile | 23 +++++++++++++++-------- scripts/pelican/pelicanconf.py | 10 +++++++++- 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 6211e22..f24d368 100644 --- a/Makefile +++ b/Makefile @@ -1,22 +1,29 @@ SHELL := /bin/bash help: - @echo 'Makefile for atlas documentation ' + @echo 'Makefile for the Atlas documentation ' @echo ' ' @echo 'Usage: ' + @echo ' ' @echo ' make html (re)generate the web site ' @echo ' make regenerate regenerate the website ' @echo ' make serve [PORT=8000] serve site at http://localhost:8000 ' @echo ' make devserver [PORT=8000] serve and regenerate together ' - @echo ' make clean remove build ' - @echo ' make clean-venv remove venv ' - @echo ' make clean-downloads remove downloads ' + @echo ' make clean remove build ' + @echo ' make clean-venv remove venv ' + @echo ' make clean-downloads remove downloads ' @echo ' make distclean remove downloads, venv, build ' @echo ' ' - @echo 'Set the WITH_DOXYGEN variable to 1/0 to skip Doxygen C++ API ' - @echo 'Set the ATLAS_SOURCE_DIR variable to existing path to avoid git download ' - @echo 'Set the ECKIT_SOURCE_DIR variable to existing path to avoid git download ' - @echo 'Set the WITH_ECKIT variable to 1/0 to add/avoid eckit within Doxygen C++ API' + @echo 'Global options: ' + @echo ' ' + @echo 'Set ATLAS_SOURCE_DIR to an existing path to avoid git download ' + @echo 'Set ECKIT_SOURCE_DIR to an existing path to avoid git download ' + @echo ' ' + @echo 'CMake options: ' + @echo ' ' + @echo 'Set WITH_DOXYGEN to 1/0 to skip Doxygen C++ API ' + @echo 'Set WITH_ECKIT to 1/0 to add/avoid eckit within Doxygen C++ API ' + @echo 'Set WITH_LATEX to 1/0 to add/avoid LaTeX within Doxygen C++ API ' @echo ' ' WITH_ECKIT ?= 0 diff --git a/scripts/pelican/pelicanconf.py b/scripts/pelican/pelicanconf.py index ef9c2a9..6248e2c 100644 --- a/scripts/pelican/pelicanconf.py +++ b/scripts/pelican/pelicanconf.py @@ -199,7 +199,15 @@ logging.warning("WITH_LATEX not set or = 0") try_with_latex = False -if not shutil.which('latex') or not try_with_latex : +if try_with_latex and not shutil.which('gs'): + raise RuntimeError( + "Ghostscript is not installed (missing 'gs'). " + "It is required to process design/grid.rst, design/mesh.rst and " + "design/interpolation.rst with WITH_DOXYGEN=1. " + "Install Ghostscript or run with WITH_LATEX=0." + ) + +if not shutil.which('latex') or not try_with_latex: logging.warning("LaTeX not found, fallback to rendering math as code") M_MATH_RENDER_AS_CODE = True From 6d412cf3cb81366a2f6814a19c04c764bf5412e4 Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Fri, 8 May 2026 15:14:44 +0200 Subject: [PATCH 4/7] issue a warning rather than throwing an error --- scripts/pelican/pelicanconf.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/scripts/pelican/pelicanconf.py b/scripts/pelican/pelicanconf.py index 6248e2c..1be9be4 100644 --- a/scripts/pelican/pelicanconf.py +++ b/scripts/pelican/pelicanconf.py @@ -200,12 +200,11 @@ try_with_latex = False if try_with_latex and not shutil.which('gs'): - raise RuntimeError( - "Ghostscript is not installed (missing 'gs'). " - "It is required to process design/grid.rst, design/mesh.rst and " - "design/interpolation.rst with WITH_DOXYGEN=1. " - "Install Ghostscript or run with WITH_LATEX=0." - ) + logging.warning( + "Ghostscript is not installed (missing 'gs'); falling back to rendering math as code. " + "Install Ghostscript to enable SVG math rendering." + ) + M_MATH_RENDER_AS_CODE = True if not shutil.which('latex') or not try_with_latex: logging.warning("LaTeX not found, fallback to rendering math as code") From 93c31c5f4b09dd0864425742ba4f325dbd35a361 Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Mon, 11 May 2026 12:05:13 +0200 Subject: [PATCH 5/7] make loading of libgs automatic --- scripts/setup.sh | 56 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/scripts/setup.sh b/scripts/setup.sh index 80f6bb0..3053571 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -98,6 +98,36 @@ eval set -- "$PARAMS" command_exists () { type "$1" &> /dev/null ; } +detect_libgs () { + local detected="" + + # Prefer common locations relative to the Ghostscript executable. + if command_exists gs; then + local gs_bin + gs_bin=$(command -v gs) + local gs_prefix + gs_prefix=$(cd "$(dirname "${gs_bin}")/.." && pwd) + for candidate in \ + "${gs_prefix}/lib/libgs.dylib" \ + "${gs_prefix}/lib/libgs.so" \ + "/opt/homebrew/lib/libgs.dylib" \ + "/usr/local/lib/libgs.dylib" \ + "/usr/lib/libgs.so"; do + if [[ -f "${candidate}" ]]; then + detected="${candidate}" + break + fi + done + fi + + # Fallback to loader-based library lookup. + if [[ -z "${detected}" ]]; then + detected=$(${_pyenv_bin} -c "import ctypes.util; print(ctypes.util.find_library('gs') or '')" 2>/dev/null) + fi + + echo "${detected}" +} + # Make sure python has required version echo "[atlas-docs] Checking Python has a suitable version" required_python_version=3.6 @@ -181,6 +211,31 @@ fi echo "[atlas-docs] Activating Python virtualenv in ${_pyenv_path}" source ${_pyenv_path}/bin/activate +# Configure LIBGS for future activations if not explicitly set. +_libgs_value="${LIBGS}" +if [[ -z "${_libgs_value}" ]]; then + _libgs_value=$(detect_libgs) +fi + +if [[ -n "${_libgs_value}" ]]; then + cat > "${_pyenv_path}/bin/atlas-docs-libgs.sh" <> "${_pyenv_path}/bin/activate" <<'EOF' + +# atlas-docs: load LIBGS if configured by setup +if [[ -f "${VIRTUAL_ENV}/bin/atlas-docs-libgs.sh" ]]; then + source "${VIRTUAL_ENV}/bin/atlas-docs-libgs.sh" +fi +EOF + fi + echo "[atlas-docs] Configured LIBGS=${_libgs_value}" +else + echo "[atlas-docs] WARNING: Could not auto-detect LIBGS. Set LIBGS manually if dvisvgm cannot find libgs." +fi + if [[ ${_pyenv_proxy} != false ]] ; then _pip_cmd="pip --disable-pip-version-check install --proxy ${_pyenv_proxy}" else @@ -195,3 +250,4 @@ ln -sf ${ATLAS_DOCS_DIR}/downloads/m.css ${ATLAS_DOCS_DIR}/scripts/pelican/m.css unset _pyenv_path _pyenv_bin _atlas_source _atlas_branch _atlas_bin unset _pyenv_force _pyenv_requirements _pyenv_proxy _atlas_https _pip_cmd USAGE_HELP +unset _libgs_value From d88315fda26e97e97125d9eadaaf3cb1f711023c Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Mon, 11 May 2026 16:14:55 +0200 Subject: [PATCH 6/7] libgs is now linked automatically if present. Otherwise a warning is returned that dvisvgm may not function properly --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index a32e80f..00ed07e 100644 --- a/README.md +++ b/README.md @@ -54,5 +54,4 @@ On MacOS, ghostscript needs to be installed as well when using LaTeX, and the LI ``` brew install ghostscript -export LIBGS=${HOMEBREW_PREFIX}/lib/libgs.dylib ``` \ No newline at end of file From 24e6194679aa22a6425e41bebb2858c0644abaff Mon Sep 17 00:00:00 2001 From: Slavko Brdar Date: Mon, 11 May 2026 17:14:50 +0200 Subject: [PATCH 7/7] automatically pick up the latest release version from Github --- Makefile | 16 +++++++++++++--- README.md | 2 +- content/index.rst | 5 ++++- 3 files changed, 18 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index f24d368..069a450 100644 --- a/Makefile +++ b/Makefile @@ -75,7 +75,7 @@ html: build/html/index.html @echo "[atlas-docs] Generated html at $(CURDIR)/build/html" @echo "[atlas-docs] To visualise, execute \"make serve\" and open browser at \"http://localhost:8000\"" -build/html/index.html: build/html/$(DOXYGEN_API)/index.html +build/html/index.html: content/generated/atlas_release_version.rst build/html/$(DOXYGEN_API)/index.html @echo "[atlas-docs] Building Pelican documentation" @$(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) @@ -99,6 +99,16 @@ build/doxygen/Doxyfile: venv/bin/activate @echo "[atlas-docs] Generating Doxyfile \"build/doxygen/Doxyfile\"" @$(GENERATE_DOXYFILE) $(GENERATEDOXYOPTS) +content/generated/atlas_release_version.rst: + @mkdir -p content/generated + @version=$$(curl -fsSL https://api.github.com/repos/ecmwf/atlas/releases/latest | sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -1); \ + if [[ -z "$$version" ]]; then \ + echo "[atlas-docs] ERROR: could not fetch latest Atlas release version from GitHub"; \ + exit 1; \ + fi; \ + printf ".. |atlas-release-version| replace:: %s\n" "$$version" > content/generated/atlas_release_version.rst; \ + echo "[atlas-docs] Latest Atlas release: $$version" + venv/bin/activate: @echo "[atlas-docs] Pre-installing required software in virtual environment" @scripts/setup.sh --atlas $(ATLAS_SOURCE_DIR) --eckit $(ECKIT_SOURCE_DIR) $(SETUPOPTS) @@ -118,14 +128,14 @@ clean-downloads: distclean: clean clean-venv clean-downloads @echo "[atlas-docs] All clean now" -regenerate: +regenerate: content/generated/atlas_release_version.rst $(PELICAN) -r $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) serve: html @echo "[atlas-docs] Open browser at http://localhost:$(PORT) (CTRL+C to end)" @$(PELICAN) -l $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) -p $(PORT) -devserver: +devserver: content/generated/atlas_release_version.rst @echo "[atlas-docs] Open browser at http://localhost:$(PORT) (CTRL+C to end)" $(PELICAN) -lr $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS) -p $(PORT) diff --git a/README.md b/README.md index 00ed07e..4a9ac66 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ Note, this requires special access credentials, and is only intended for officia Troubleshooting --------------- -On MacOS, ghostscript needs to be installed as well when using LaTeX, and the LIBGS environment variable needs to be set. +On MacOS, ghostscript needs to be installed when using LaTeX. ``` brew install ghostscript diff --git a/content/index.rst b/content/index.rst index 11c3a83..693e730 100644 --- a/content/index.rst +++ b/content/index.rst @@ -7,6 +7,9 @@ Atlas :description: Data structure library for NWP and Climate Modelling :summary: Data structure library for NWP and Climate Modelling :hide_navbar_brand: True + +.. include:: generated/atlas_release_version.rst + :landing: .. container:: m-row @@ -38,5 +41,5 @@ Atlas .. class:: m-text-center m-text m-warning m-noindent - | Version 0.36.0 released + | Version |atlas-release-version| released