Some fixes and improvements

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
@@ -68,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)
 
@@ -92,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)
@@ -111,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:
+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)
 

README.md

@@ -50,9 +50,8 @@ 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
-export LIBGS=${HOMEBREW_PREFIX}/lib/libgs.dylib
 ```

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
 

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")
 
@@ -194,7 +199,14 @@
   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'):
+  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")
     M_MATH_RENDER_AS_CODE = True
 

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
@@ -114,8 +144,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}\")"
@@ -182,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" <<EOF
+export LIBGS="${_libgs_value}"
+EOF
+
+    if ! grep -q "atlas-docs-libgs.sh" "${_pyenv_path}/bin/activate"; then
+        cat >> "${_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
@@ -196,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