Update docs build (#456)

- updates readthedocs runner to 24.04 and py313
- fixes for sphinx 8
- applies the readthedocs theme
- fixes all but 1 warning which fixes a bunch of rendering errors
- fixes some typos

Author: scasagrande

.readthedocs.yml

@@ -1,15 +1,17 @@
 version: 2
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    python: "3.9"
+    python: "3.13"
 
 sphinx:
   builder: html
   configuration: doc/source/conf.py
   fail_on_warning: false
 
 python:
-   install:
-     - method: pip
-       path: .
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

doc/source/conf.py

@@ -39,7 +39,7 @@
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext"}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -49,7 +49,7 @@
 
 # General information about the project.
 project = "InstrumentKit Library"
-copyright = "2013-2022, Steven Casagrande"
+copyright = "2013-2025, Steven Casagrande"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -99,7 +99,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -128,7 +128,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -266,7 +266,6 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    "http://docs.python.org/": None,
     "numpy": ("http://docs.scipy.org/doc/numpy", None),
     "serial": ("http://pyserial.sourceforge.net/", None),
     "pint": ("https://pint.readthedocs.io/en/stable/", None),

doc/source/devguide/testing.rst

@@ -84,7 +84,7 @@ Expected Protocols
 ==================
 
 As an example of asserting correctness of implemented protocols, let's consider
-a simple test case for :class:`instruments.srs.SRSDG645``::
+a simple test case for :class:`instruments.srs.SRSDG645`::
 
 	def test_srsdg645_output_level():
 	    """

license/AUTHOR.TXT

@@ -4,4 +4,4 @@ Steven Casagrande
 [email protected]
 twitter.com/stevecasagrande
 
-2012-2022
+2012-2025

pyproject.toml

@@ -56,6 +56,10 @@ dev = [
     "pyvisa-sim",
     "six",
 ]
+docs = [
+    "sphinx~=8.2.0",
+    "sphinx_rtd_theme"
+]
 
 [tool.setuptools]
 include-package-data = true

src/instruments/abstract_instruments/instrument.py

@@ -256,8 +256,8 @@ def write(self, msg):
         channel related work.
 
         .. seealso:: `Instrument.sendcmd` if you wish to send a string to the
-        instrument, while still having InstrumentKit handle termination
-        characters and other communication channel related work.
+            instrument, while still having InstrumentKit handle termination
+            characters and other communication channel related work.
 
         :param str msg: String that will be written to the filelike object
             (`Instrument._file`) attached to this instrument.

src/instruments/holzworth/holzworth_hs9000.py

@@ -34,7 +34,7 @@ class Channel(SGChannel):
         Class representing a physical channel on the Holzworth HS9000
 
         .. warning:: This class should NOT be manually created by the user. It
-        is designed to be initialized by the `HS9000` class.
+            is designed to be initialized by the `HS9000` class.
         """
 
         def __init__(self, hs, idx_chan):

src/instruments/minghe/mhs5200a.py

@@ -112,7 +112,7 @@ def frequency(self):
             Gets/Sets the frequency of this channel.
 
             :units: As specified (if a `~pint.Quantity`) or assumed to be
-            of units hertz.
+                of units hertz.
             :type: `~pint.Quantity`
             """
             query = f":r{self._chan}f"
@@ -152,7 +152,7 @@ def phase(self):
             Gets/Sets the phase of this channel.
 
             :units: As specified (if a `~pint.Quantity`) or assumed to be
-            of degrees.
+                of degrees.
             :type: `~pint.Quantity`
             """
             # need to convert
@@ -201,10 +201,10 @@ def channel(self):
 
         For instance, this would print the counts of the first channel::
 
-        >>> import instruments as ik
-        >>> mhs = ik.minghe.MHS5200.open_serial(vid=1027, pid=24577,
-        baud=19200, timeout=1)
-        >>> print(mhs.channel[0].frequency)
+            >>> import instruments as ik
+            >>> mhs = ik.minghe.MHS5200.open_serial(vid=1027, pid=24577,
+            baud=19200, timeout=1)
+            >>> print(mhs.channel[0].frequency)
 
         :rtype: `list`[`MHS5200.Channel`]
         """

src/instruments/newport/agilis.py

@@ -141,11 +141,11 @@ def jog(self):
             -3 — Negative direction, 1700 steps/s at max. step amplitude.
             -2 — Negative direction, 100 step/s at max. step amplitude.
             -1 — Negative direction, 5 steps/s at defined step amplitude.
-             0 — No move, go to READY state.
-             1 — Positive direction, 5 steps/s at defined step amplitude.
-             2 — Positive direction, 100 steps/s at max. step amplitude.
-             3 — Positive direction, 1700 steps/s at max. step amplitude.
-             4 — Positive direction, 666 steps/s at defined step amplitude.
+            +0 — No move, go to READY state.
+            +1 — Positive direction, 5 steps/s at defined step amplitude.
+            +2 — Positive direction, 100 steps/s at max. step amplitude.
+            +3 — Positive direction, 1700 steps/s at max. step amplitude.
+            +4 — Positive direction, 666 steps/s at defined step amplitude.
 
             :return: Jog motion set
             :rtype: `int`
@@ -427,12 +427,13 @@ def limit_status(self):
 
         Returns the limit switch status of the controller. Possible returns
         are:
-        - PH0: No limit switch is active
-        - PH1: Limit switch of axis #1 (X) is active,
-               limit switch of axis #2 (Y)  is not active
-        - PH2: Limit switch of axis #2 (Y) is active,
-               limit switch of axis #1 (X) is not active
-        - PH3: Limit switches of axis #1 (X) and axis #2 (Y) are active
+
+            - PH0: No limit switch is active
+            - PH1: Limit switch of axis #1 (X) is active,
+                   limit switch of axis #2 (Y)  is not active
+            - PH2: Limit switch of axis #2 (Y) is active,
+                   limit switch of axis #1 (X) is not active
+            - PH3: Limit switches of axis #1 (X) and axis #2 (Y) are active
 
         If device has no limit switch, this routine always returns PH0
         """
@@ -443,7 +444,7 @@ def limit_status(self):
     @property
     def sleep_time(self):
         """
-        The device often times out. Therefore a sleep time can be set. The
+        The device often times out. Therefore, a sleep time can be set. The
         routine will wait for this amount (in seconds) every time after a
         command or a query are sent.
         Setting the sleep time: Give time in seconds

src/instruments/newport/newport_pmc8742.py

@@ -445,23 +445,23 @@ def controller_configuration(self):
             """Get / set configuration of some of the controller’s features.
 
             Configuration is given as a bit mask. If changed, please save
-            the settings afterwards if you would like to do so. See
+            the settings afterward if you would like to do so. See
             `save_settings`.
 
             The bitmask to be set can be either given as a number, or as a
             string of the mask itself. The following values are equivalent:
             3, 0b11, "11"
 
-            Bit 0:
-                Value 0: Perform auto motor detection. Check and set motor
-                    type automatically when commanded to move.
-                Value 1: Do not perform auto motor detection on move.
-            Bit 1:
-                Value 0: Do not scan for motors connected to controllers upon
-                    reboot (Performs ‘MC’ command upon power-up, reset or
-                    reboot).
-                Value 1: Scan for motors connected to controller upon power-up
-                    or reset.
+            - Bit 0:
+                - Value 0: Perform auto motor detection. Check and set motor
+                           type automatically when commanded to move.
+                - Value 1: Do not perform auto motor detection on move.
+            - Bit 1:
+                - Value 0: Do not scan for motors connected to controllers upon
+                           reboot (Performs ‘MC’ command upon power-up, reset or
+                           reboot).
+                - Value 1: Scan for motors connected to controller upon power-up
+                           or reset.
 
             :return: Bitmask of the controller configuration.
             :rtype: str, binary configuration
@@ -547,12 +547,12 @@ def recall_parameters(self, value=0):
             saved in its non-volatile memory. It is useful when, for example,
             the user has been exploring and changing parameters (e.g., velocity)
             but then chooses to reload from previously stored, qualified
-            settings. Note that “*RCL 0” command just restores the working
+            settings. Note that `*RCL 0` command just restores the working
             parameters to factory default settings. It does not change the
             settings saved in EEPROM.
 
             :param value: 0 -> Recall factory default,
-                1 -> Recall last saved settings
+                          1 -> Recall last saved settings
             :type int:
             """
             self.sendcmd(f"*RCL{1 if value else 0}", axs=False)
@@ -564,7 +564,7 @@ def reset(self):
             hard reset, see the `purge` command.
 
             ..note:: It might take up to 30 seconds to re-establish
-            communications via TCP/IP
+                communications via TCP/IP
             """
             self.sendcmd("*RST", axs=False)
 
@@ -681,19 +681,19 @@ def controller_configuration(self):
         """Get / set configuration of some of the controller’s features.
 
         Configuration is given as a bit mask. If changed, please save
-        the settings afterwards if you would like to do so. See
+        the settings afterward if you would like to do so. See
         `save_settings`.
 
-        Bit 0:
-            Value 0: Perform auto motor detection. Check and set motor
-                type automatically when commanded to move.
-            Value 1: Do not perform auto motor detection on move.
-        Bit 1:
-            Value 0: Do not scan for motors connected to controllers upon
-                reboot (Performs ‘MC’ command upon power-up, reset or
-                reboot).
-            Value 1: Scan for motors connected to controller upon power-up
-                or reset.
+        - Bit 0:
+            - Value 0: Perform auto motor detection. Check and set motor
+                       type automatically when commanded to move.
+            - Value 1: Do not perform auto motor detection on move.
+        - Bit 1:
+            - Value 0: Do not scan for motors connected to controllers upon
+                       reboot (Performs ‘MC’ command upon power-up, reset or
+                       reboot).
+            - Value 1: Scan for motors connected to controller upon power-up
+                       or reset.
 
         :return: Bitmask of the controller configuration.
         :rtype: str
@@ -944,7 +944,7 @@ def scan_controllers(self):
             Bit:    Value: (True: 1, False: 0)
             0       Address conflict?
             1:      Controller with address 1 exists?
-                ...
+            <...>
             31:      Controller with address 31 exists
 
         Bits 1—31 are one-to-one mapped to controller addresses 1—31. The
@@ -1026,6 +1026,7 @@ def scan(self, value=2):
         Scans the RS-485 network for connected controllers and set the
         addresses automatically. Three possible scan modes can be
         selected:
+
         Mode 0:
             Primary controller scans the network but does not resolve
             any address conflicts.
@@ -1086,7 +1087,7 @@ def recall_parameters(self, value=0):
         saved in its non-volatile memory. It is useful when, for example,
         the user has been exploring and changing parameters (e.g., velocity)
         but then chooses to reload from previously stored, qualified
-        settings. Note that “*RCL 0” command just restores the working
+        settings. Note that `*RCL 0` command just restores the working
         parameters to factory default settings. It does not change the
         settings saved in EEPROM.