diff --git a/Makefile b/Makefile index 02aa5e9..069a450 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 @@ -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) diff --git a/README.md b/README.md index a32e80f..4a9ac66 100644 --- a/README.md +++ b/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 ``` \ No newline at end of file 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 diff --git a/scripts/pelican/pelicanconf.py b/scripts/pelican/pelicanconf.py index 2a2cc25..1be9be4 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") @@ -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 diff --git a/scripts/setup.sh b/scripts/setup.sh index c9cd0d3..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 @@ -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" <> "${_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