Merge pull request #115 from dihm/rtd_fixes

Rtd fixes

Author: dihm

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).

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

docs/source/api/index.rst

@@ -4,7 +4,6 @@ API Reference
 
 .. autosummary::
    :toctree: _autosummary
-   :template: autosummary-module.rst
    :recursive:
 
    labscript_utils

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
 
@@ -103,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

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]

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:
@@ -17,9 +24,10 @@ sphinx:
   fail_on_warning: false
 
 # Optionally build your docs in additional formats such as PDF
-formats:
-  - pdf
-  - epub
+# Disable since h5_lock breaks build when sphinx is run twice in a row
+#formats:
+#  - pdf
+# - epub
 
 # Optionally set the requirements required to build your docs
 python: