Many fixes to the default_role not working

docs/sphinx/conf.py

@@ -77,7 +77,7 @@
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-default_role = "py:obj"
+default_role = "obj"
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 # add_function_parentheses = True
@@ -104,7 +104,7 @@
 
 # Intersphinx mappings
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.9", None),
+    "python": ("https://docs.python.org/3.11", None),
     "clu": ("https://clu.readthedocs.io/en/latest/", None),
 }
 
@@ -124,6 +124,7 @@
 
 rst_epilog = f"""
 .. |lvmgort_version| replace:: {__version__}
+.. default-role:: py:obj
 """
 
 

src/gort/devices/enclosure.py

@@ -128,7 +128,7 @@ async def stop(self):
         await self.actor.commands.dome.commands.stop()
 
     async def is_local(self):
-        """Returns `True` if the enclosure is in local mode."""
+        """Returns :obj:`True` if the enclosure is in local mode."""
 
         status = await self.status()
         safety_status_labels = status.get("safety_status_labels", None)

src/gort/devices/guider.py

@@ -78,10 +78,10 @@ async def wait_until_guiding(
         ----------
         guide_tolerance
             The minimum separation, in arcsec, between the measured and desired
-            positions that needs to be reached before returning. If `None`,
+            positions that needs to be reached before returning. If :obj:`None`,
             waits until guiding (as opposed to acquisition) begins.
         timeout
-            Maximum time, in seconds, to wait before returning. If `None`,
+            Maximum time, in seconds, to wait before returning. If :obj:`None`,
             waits indefinitely. If the timeout is reached it does not
             raise an exception.
 
@@ -94,7 +94,7 @@ async def wait_until_guiding(
         separation
             The current separation.
         timedout
-            `True` if the acquisition timed out.
+            :obj:`True` if the acquisition timed out.
 
         """
 
@@ -127,7 +127,7 @@ async def expose(self, *args, continuous: bool = False, **kwargs):
         args,kwargs
             Arguments to be passed to the guider expose command.
         continuous
-            Whether to expose the camera continuously. If `False`
+            Whether to expose the camera continuously. If :obj:`False`
             it takes a single exposure.
 
         """
@@ -151,11 +151,11 @@ async def focus(
         Parameters
         ----------
         inplace
-            If `True`, focuses the telescope where it is pointing at. Otherwise
+            If :obj:`True`, focuses the telescope where it is pointing at. Otherwise
             points to zenith.
         guess
-            The initial guess for the focuser position. If `None`, the default value
-            from the configuration file is used.
+            The initial guess for the focuser position. If :obj:`None`, the
+            default value from the configuration file is used.
         step_size
             The size, in focuser units, of each step.
         steps
@@ -238,7 +238,7 @@ async def guide(
         Parameters
         ----------
         ra,dec
-            The coordinates to acquire. If `None`, the current telescope
+            The coordinates to acquire. If :obj:`None`, the current telescope
             coordinates are used.
         exposure_time
             The exposure time of the AG integrations.
@@ -438,7 +438,7 @@ async def expose(self, *args, continuous: bool = False, **kwargs):
         args,kwargs
             Arguments to be passed to :obj:`.Guider.expose`.
         continuous
-            Whether to expose the camera continuously. If `False`
+            Whether to expose the camera continuously. If :obj:`False`
             it takes a single exposure.
 
         """
@@ -487,13 +487,14 @@ async def focus(
         Parameters
         ----------
         inplace
-            If `True`, focuses the telescopes where they are pointing at. Otherwise
+            If :obj:`True`, focuses the telescopes where they are pointing at. Otherwise
             points to zenith.
         guess
-            The initial guesses for focuser position. If `None`, the default values
-            from the configuration file are used. It can also be a float value,
-            which will be used for all telescopes, or a mapping of telescope name
-            to guess value. Missing values will default to the configuration value.
+            The initial guesses for focuser position. If :obj:`None`, the default
+            values from the configuration file are used. It can also be a float
+            value, which will be used for all telescopes, or a mapping of telescope
+            name to guess value. Missing values will default to the configuration
+            value.
         step_size
             The size, in focuser units, of each step.
         steps
@@ -576,19 +577,19 @@ async def wait_until_guiding(
             List of telescopes to wait for convergence.
         guide_tolerance
             The minimum separation, in arcsec, between the measured and desired
-            positions that needs to be reached before returning. If `None`,
+            positions that needs to be reached before returning. If :obj:`None`,
             waits until guiding (as opposed to acquisition) begins.
         timeout
-            Maximum time, in seconds, to wait before returning. If `None`,
+            Maximum time, in seconds, to wait before returning. If :obj:`None`,
             waits indefinitely. If the timeout is reached it does not
             raise an exception.
 
         Returns
         -------
         status
             A dictionary with the telescope names and a tuple indicating whether
-            the desired minimum separation was reached. the current
-            :obj:`.GuiderStatus`, and the current separation for that telescope.
+            the desired minimum separation was reached. The current
+            ``GuiderStatus``, and the current separation for that telescope.
 
         """
 

src/gort/devices/spec.py

@@ -63,7 +63,7 @@ async def power(self, devices: str | list[str], on: bool = True):
             The device to power on/off. Either ``'shutter'``, ``'hartmann_left'``,
             or ``'hartmann_right'``. Can be a list of devices to modify.
         on
-            If `True` powers on the device; otherwise powers it down.
+            If :obj:`True` powers on the device; otherwise powers it down.
 
         """
 
@@ -203,7 +203,7 @@ async def init(self, devices: str | list[str], home: bool = True):
             The device to act on. Either ``'shutter'``, ``'hartmann_left'``,
             or ``'hartmann_right'``. Can be a list of devices to initialise.
         home
-            If `True` homes the devices after initialising them.
+            If :obj:`True` homes the devices after initialising them.
 
         """
 
@@ -228,7 +228,7 @@ async def status(self, simple: bool = False):
         Parameters
         ----------
         simple
-            If `True` returns a short version of the status.
+            If :obj:`True` returns a short version of the status.
 
         """
 
@@ -238,20 +238,20 @@ async def status(self, simple: bool = False):
         return flatten_reply.get("status", {})
 
     async def is_idle(self):
-        """Returns `True` if the spectrograph is idle and ready to expose."""
+        """Returns :obj:`True` if the spectrograph is idle and ready to expose."""
 
         status = await self.status(simple=True)
         names = status["status_names"]
         return "IDLE" in names and "READOUT_PENDING" not in names
 
     async def is_exposing(self):
-        """Returns `True` if the spectrograph is exposing."""
+        """Returns :obj:`True` if the spectrograph is exposing."""
 
         status = await self.status(simple=True)
         return "EXPOSING" in status["status_names"]
 
     async def is_reading(self):
-        """Returns `True` if the spectrograph is idle and ready to expose."""
+        """Returns :obj:`True` if the spectrograph is idle and ready to expose."""
 
         status = await self.status(simple=True)
         return "READING" in status["status_names"]
@@ -307,7 +307,7 @@ async def status(self, simple: bool = False) -> dict[str, dict]:
         Parameters
         ----------
         simple
-            If `True` returns a short version of the status.
+            If :obj:`True` returns a short version of the status.
 
         """
 
@@ -327,7 +327,7 @@ def get_expno(self):
         return expno
 
     async def are_idle(self):
-        """Returns `True` if all the spectrographs are idle and ready to expose."""
+        """Returns :obj:`True` if all the spectrographs are idle and ready to expose."""
 
         return all(await self.call_device_method(Spectrograph.is_idle))
 
@@ -355,7 +355,7 @@ async def expose(
             Additional data to add to the headers.
         show_progress
             Displays a progress bar with the elapsed exposure time.
-            If `None` (the default), will show the progress bar only
+            If :obj:`None` (the default), will show the progress bar only
             in interactive sessions.
         async_readout
             Returns after integration completes. Readout is initiated

src/gort/devices/telescope.py

@@ -376,7 +376,7 @@ async def initialise(self, home: bool | None = None):
         Parameters
         ----------
         home
-            If `True`, runs the homing routine after initialising.
+            If :obj:`True`, runs the homing routine after initialising.
 
         """
 
@@ -400,13 +400,13 @@ async def home(
         Parameters
         ---------
         home_telescope
-            Homes the telescope. Defaults to `True`.
+            Homes the telescope. Defaults to :obj:`True`.
         home_km
-            Homes the K-mirror, if present. Defaults to `True`.
+            Homes the K-mirror, if present. Defaults to :obj:`True`.
         home_focuser
-            Homes the focuser. Defaults to `False`.
+            Homes the focuser. Defaults to :obj:`False`.
         home_fibsel
-            Homes the fibre selector, if present. Defaults to `False`.
+            Homes the fibre selector, if present. Defaults to :obj:`False`.
 
         """
 
@@ -549,7 +549,7 @@ async def goto_coordinates(
             Whether to move the k-mirror into position. Only when
             the coordinates provided are RA/Dec.
         altaz_tracking
-            If `True`, starts tracking after moving to alt/az coordinates.
+            If :obj:`True`, starts tracking after moving to alt/az coordinates.
             By defaul the PWI won't track with those coordinates.
         use_pointing_offsets
             If defined, uses the RA/Dec calibrations offsets for the telescope.
@@ -855,13 +855,13 @@ async def home(
         Parameters
         ---------
         home_telescopes
-            Homes the telescopes. Defaults to `True`.
+            Homes the telescopes. Defaults to :obj:`True`.
         home_kms
-            Homes the K-mirrors, if present. Defaults to `True`.
+            Homes the K-mirrors, if present. Defaults to :obj:`True`.
         home_focusers
-            Homes the focusers. Defaults to `False`.
+            Homes the focusers. Defaults to :obj:`False`.
         home_fibsel
-            Homes the fibre selector, if present. Defaults to `False`.
+            Homes the fibre selector, if present. Defaults to :obj:`False`.
 
         """
 
@@ -936,7 +936,7 @@ async def goto_coordinates_all(
             Whether to move the k-mirror into position. Only when
             the coordinates provided are RA/Dec.
         altaz_tracking
-            If `True`, starts tracking after moving to alt/az coordinates.
+            If :obj:`True`, starts tracking after moving to alt/az coordinates.
             By defaul the PWI won't track with those coordinates.
         force
             Move the telescopes even if mode is local.

src/gort/exposure.py

@@ -46,7 +46,7 @@ class Exposure(asyncio.Future["Exposure"]):
     gort
         A `.Gort` instance to communicate with the actors.
     exp_no
-        The exposure sequence number. If `None`, the next valid
+        The exposure sequence number. If :obj:`None`, the next valid
         sequence number will be used.
     flavour
         The image type. Defaults to ``'object'``.
@@ -135,7 +135,7 @@ async def expose(
             the returned :obj:`.Exposure` object.
         show_progress
             Displays a progress bar with the elapsed exposure time.
-            If `None` (the default), will show the progress bar only
+            If :obj:`None` (the default), will show the progress bar only
             in interactive sessions.
         object
             The object name to be passed to the header.

src/gort/gort.py

@@ -83,13 +83,13 @@ class GortClient(AMQPClient):
     password
         The password to connect to the exchange.
     use_rich_output
-        If `True`, uses ``rich`` to provide colourised tracebacks and prettier
-        outputs.
+        If :obj:`True`, uses ``rich`` to provide colourised tracebacks and
+        prettier outputs.
     log_file_path
         The path where to save GORT's log. File logs are always saved with `DEBUG`
-        logging level. If `None`, a temporary file will be used whose path can be
-        retrieved by calling `.get_log_path`. If `False`, no file logging
-        will happen.
+        logging level. If :obj:`None`, a temporary file will be used whose path
+        can be retrieved by calling :obj:`.get_log_path`. If :obj:`False`, no file
+        logging will happen.
 
     """
 
@@ -227,7 +227,7 @@ def _showtraceback(*args, **kwargs):
             custom__showtraceback_closure(IPYTHON._showtraceback)
 
     def get_log_path(self):
-        """Returns the path of the log file. `None` if not logging to file."""
+        """Returns the path of the log file. :obj:`None` if not logging to file."""
 
         return self.log.log_filename
 
@@ -262,11 +262,11 @@ def add_device(self, class_: Type[DevType], *args, **kwargs) -> DevType:
 
     @property
     def connected(self):
-        """Returns `True` if the client is connected."""
+        """Returns :obj:`True` if the client is connected."""
 
         return self.connection and self.connection.connection is not None
 
-    def add_actor(self, actor: str, device: "GortDevice" | None = None):
+    def add_actor(self, actor: str, device: GortDevice | None = None):
         """Adds an actor to the programmatic API.
 
         Parameters
@@ -289,8 +289,8 @@ def set_verbosity(self, verbosity: str | int | None = None):
         Parameters
         ----------
         verbosity
-            The level of verbosity. Can be a string level name, an integer, or `None`,
-            in which case the default verbosity will be used.
+            The level of verbosity. Can be a string level name, an integer, or
+            :obj:`None`, in which case the default verbosity will be used.
 
         """
 
@@ -580,9 +580,9 @@ class Gort(GortClient):
         The level of logging verbosity.
     on_interrupt
         Action to perform if the loop receives an interrupt signal during
-        execution. The only options are `None` (do nothing, currently running
-        commands will continue), or ``stop'`` which will stop the telescopes
-        and guiders before exiting.
+        execution. The only options are :obj:`None` (do nothing, currently
+        running commands will continue), or ``stop'`` which will stop the
+        telescopes and guiders before exiting.
 
     """
 

src/gort/observer.py

@@ -65,7 +65,7 @@ def __repr__(self):
 
     @property
     def has_standards(self):
-        """Returns `True` if standards will be observed."""
+        """Returns :obj:`True` if standards will be observed."""
 
         return len(self.standards.standards) > 0