Merge pull request #133 from dihm/sphinx_updates

Update sphinx build and ensure RTD stable versioning is correct

Author: dihm

docs/Makefile

@@ -7,12 +7,18 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
+AUTOSUMMARYDIR = source/devices/_apidoc
 
 # 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 apidoc 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\devices\_apidoc
 
 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/conf.py

@@ -13,6 +13,7 @@
 import os
 from pathlib import Path
 from jinja2 import FileSystemLoader, Environment
+import importlib.metadata
 
 # -- Project information (unique to each project) -------------------------------------
 
@@ -21,7 +22,7 @@
 author = "labscript suite contributors"
 
 # The full version, including alpha/beta/rc tags
-from labscript_devices import __version__ as version  # noqa: E402
+version = importlib.metadata.version('labscript-devices')
 
 release = version
 
@@ -49,7 +50,7 @@
 
 autodoc_typehints = 'description'
 autoclass_content = 'both'  # options: 'both', 'class', 'init'
-autodoc_mock_imports = ['PyDAQmx','labscript_utils']
+autodoc_mock_imports = ['PyDAQmx','labscript_utils.h5_lock']
 
 # Prefix each autosectionlabel with the name of the document it is in and a colon
 autosectionlabel_prefix_document = True
@@ -64,7 +65,10 @@
 exclude_patterns = []
 
 # The suffix(es) of source filenames.
-source_suffix = ['.rst', '.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # The master toctree document.
 master_doc = 'index'
@@ -85,7 +89,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

docs/source/index.rst

@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-labscript-devices
-=================
+labscript-devices |version|
+===========================
 
 This portion of the **labscript-suite** contains the plugin architecture for controlling experimental hardware.
 In particular, this code provides the interface between **labscript** high-level instructions and hardware-specific instructions, the communication interface to send those instructions to the hardware, and the **BLACS** instrument control interface.

docs/source/user_devices.rst

@@ -32,4 +32,4 @@ Please direct any questions regarding these repositories to their respective own
 * `NAQS Lab <https://github.com/naqslab/naqslab_devices>`__
 * `Vladan Vuletic Group Rb Lab, MIT <https://github.com/zakv/RbLab_user_devices>`__
 
-If you would like to add your repository to this list, :doc:`please contact us or make a pull request<labscript-suite:contributing>`.
+If you would like to add your repository to this list, :doc:`please contact us or make a pull request<labscript-suite:project/contributing>`.

pyproject.toml

@@ -59,7 +59,7 @@ Tracker = "https://github.com/labscript-suite/labscript-devices/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.2",
+    "myst_parser==4.0.1",
 ]

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: