From 2589ce07d8237c786313220e54bca3e19091b9d3 Mon Sep 17 00:00:00 2001 From: David Meyer Date: Tue, 17 Jun 2025 10:45:05 -0400 Subject: [PATCH 1/4] Do not use setuptools-scm to define version at runtime for RTD builds --- docs/source/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 403ebbf..a755667 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,6 +14,7 @@ import os from pathlib import Path from jinja2 import FileSystemLoader, Environment +import importlib.metadata # -- Project information (unique to each project) ------------------------------------- @@ -22,7 +23,7 @@ author = "labscript suite contributors" # The full version, including alpha/beta/rc tags -from labscript_utils import __version__ as version # noqa: E402 +version = importlib.metadata.version('labscript-utils') release = version From d93209f5318fb1329c9990ec46922e766a11a2d6 Mon Sep 17 00:00:00 2001 From: David Meyer Date: Tue, 17 Jun 2025 10:49:28 -0400 Subject: [PATCH 2/4] Esnure RTD builds pull full git repo so versions are properly computed by setuptools-scm on install --- readthedocs.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/readthedocs.yaml b/readthedocs.yaml index 4f8b68e..ef9f9a0 100644 --- a/readthedocs.yaml +++ b/readthedocs.yaml @@ -9,6 +9,13 @@ build: os: ubuntu-22.04 tools: python: "3.11" + jobs: + # ensure full git repo is pulled so setuptools_scm gets versions correctly on install + # https://docs.readthedocs.com/platform/stable/build-customization.html#unshallow-git-clone + post_checkout: + - git fetch --unshallow || true + - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true + - git fetch --all --tags || true # Build documentation in the docs/ directory with Sphinx sphinx: From 7fd55208198886d0439b8d8eba74dfc9981f2f2f Mon Sep 17 00:00:00 2001 From: David Meyer Date: Tue, 17 Jun 2025 13:01:21 -0400 Subject: [PATCH 3/4] Update docs makefiles to clean intermediate autosummary directory --- docs/Makefile | 8 +++++++- docs/make.bat | 8 ++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..82e8b02 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -7,12 +7,18 @@ SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build +AUTOSUMMARYDIR = source/api/_autosummary # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +clean: + @echo "Removing autosummary directory" + @rm -rf $(AUTOSUMMARYDIR) + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help clean Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/make.bat b/docs/make.bat index 9534b01..f5eb0b8 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -9,8 +9,10 @@ if "%SPHINXBUILD%" == "" ( ) set SOURCEDIR=source set BUILDDIR=build +set AUTOSUMMARYDIR=source\api\_autosummary if "%1" == "" goto help +if "%1" == "clean" goto clean %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( @@ -30,6 +32,12 @@ goto end :help %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:clean +echo Removing autosummary directory +rmdir /s/q %AUTOSUMMARYDIR% +%SPHINXBUILD% -M clean %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% :end popd From 216e7b7de76be8fc14e5e5ba5cd325b60978da78 Mon Sep 17 00:00:00 2001 From: David Meyer Date: Tue, 17 Jun 2025 15:14:13 -0400 Subject: [PATCH 4/4] Update docs pins (primarily sphinx=8.2.3) to circumvent environment errors when running the build multiple times. Ultimate cause is still unknown, but appears to do with some interaction between h5_lock and the pickled environment. Upgrade sphinx>=7.4 resulted in minor changes. We have to go back to their built-in module template and intersphinx mapping to `qt` has to have a proper URI target. --- docs/source/api/index.rst | 1 - docs/source/conf.py | 2 +- pyproject.toml | 6 +++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst index 59bde58..bafafcb 100644 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.rst @@ -4,7 +4,6 @@ API Reference .. autosummary:: :toctree: _autosummary - :template: autosummary-module.rst :recursive: labscript_utils diff --git a/docs/source/conf.py b/docs/source/conf.py index a755667..2fe9d17 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -104,7 +104,7 @@ 'h5py': ('https://docs.h5py.org/en/stable/', None), 'pydaqmx': ('https://pythonhosted.org/PyDAQmx/', None), 'qt': ( - '', + 'https://riverbankcomputing.com/static/Docs/PyQt5/', 'pyqt5-modified-objects.inv', ) # from https://github.com/MSLNZ/msl-qt/blob/master/docs/create_pyqt_objects.py # under MIT License diff --git a/pyproject.toml b/pyproject.toml index e7bb065..53ec1e5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,9 +56,9 @@ Tracker = "https://github.com/labscript-suite/labscript-utils/issues/" [project.optional-dependencies] docs = [ "PyQt5", - "Sphinx==7.2.6", - "sphinx-rtd-theme==2.0.0", - "myst_parser==2.0.0", + "Sphinx==8.2.3", + "sphinx-rtd-theme==3.0.1", + "myst_parser==4.0.1", ] [project.scripts]