From 7c7dfb67a61451578d350527dd0243b739b13688 Mon Sep 17 00:00:00 2001
From: Drew Devereux <drew.devereux@csiro.au>
Date: Mon, 12 Oct 2020 11:30:17 +0800
Subject: [PATCH] docs cleanup
---
docs/source/SKABaseDevice.rst | 5 +++++
docs/source/State_Machine.rst | 12 ++++++++----
src/ska/base/base_device.py | 26 +++++++++++++-------------
src/ska/base/commands.py | 2 +-
src/ska/base/logger_device.py | 2 +-
src/ska/base/master_device.py | 2 +-
src/ska/base/obs_device.py | 2 +-
src/ska/base/state_machine.py | 3 +++
src/ska/base/subarray_device.py | 30 +++++++++++++++---------------
tests/conftest.py | 2 +-
tests/test_base_device.py | 10 ++++++++--
11 files changed, 57 insertions(+), 39 deletions(-)
diff --git a/docs/source/SKABaseDevice.rst b/docs/source/SKABaseDevice.rst
index 9d410327..49deb8eb 100644
--- a/docs/source/SKABaseDevice.rst
+++ b/docs/source/SKABaseDevice.rst
@@ -10,6 +10,11 @@ SKA BaseDevice
:maxdepth: 2
.. automodule:: ska.base.base_device
+
+.. autoclass:: ska.base.DeviceStateModel
+ :members:
+ :undoc-members:
+
.. autoclass:: ska.base.SKABaseDevice
:members:
:undoc-members:
diff --git a/docs/source/State_Machine.rst b/docs/source/State_Machine.rst
index 929d3191..dfb27103 100644
--- a/docs/source/State_Machine.rst
+++ b/docs/source/State_Machine.rst
@@ -151,11 +151,15 @@ observations (currently only subarray devices).
API
---
-.. toctree::
- :maxdepth: 2
-
-
.. automodule:: ska.base.state_machine
:members:
:undoc-members:
+.. autoclass:: OperationStateMachine
+ :members:
+
+.. autoclass:: AdminModeStateMachine
+ :members:
+
+.. autoclass:: ObservationStateMachine
+ :members:
diff --git a/src/ska/base/base_device.py b/src/ska/base/base_device.py
index f7a24354..2d8b824b 100644
--- a/src/ska/base/base_device.py
+++ b/src/ska/base/base_device.py
@@ -308,7 +308,7 @@ class LoggingUtils:
# PROTECTED REGION END # // SKABaseDevice.additionnal_import
-__all__ = ["SKABaseDevice", "main"]
+__all__ = ["DeviceStateModel", "SKABaseDevice", "main"]
class DeviceStateModel:
@@ -527,9 +527,9 @@ class DeviceStateModel:
combination of admin_mode and op_state (e.g. OFFLINE and ON).
:param op_state: the target operational state (optional)
- :type op_state: string
+ :type op_state: :py:class:`tango.DevState`
:param admin_mode: the target admin mode (optional)
- :type admin_mode: string
+ :type admin_mode: :py:class:`~ska.base.control_model.AdminMode`
"""
if admin_mode is None:
admin_mode = self._admin_mode_state_machine.state
@@ -571,7 +571,7 @@ class SKABaseDevice(Device):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: DeviceStateModel
+ :type state_model: :py:class:`DeviceStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -804,7 +804,7 @@ class SKABaseDevice(Device):
callback
:param admin_mode: the new admin_mode value
- :type admin_mode: AdminMode
+ :type admin_mode: :py:class:`~ska.base.control_model.AdminMode`
"""
self.push_change_event("adminMode", admin_mode)
self.push_archive_event("adminMode", admin_mode)
@@ -815,7 +815,7 @@ class SKABaseDevice(Device):
callback
:param state: the new state value
- :type state: DevState
+ :type state: :py:class:`tango.DevState`
"""
if state != self.get_state():
self.logger.info(f"Device state changed from {self.get_state()} to {state}")
@@ -828,7 +828,7 @@ class SKABaseDevice(Device):
events are pushed.
:param state: the new state
- :type state: tango.DevState
+ :type state: :py:class:`tango.DevState`
"""
super().set_state(state)
self.push_change_event("state")
@@ -1057,7 +1057,7 @@ class SKABaseDevice(Device):
Sets Admin Mode of the device.
:param value: Admin Mode of the device.
- :type value: AdminMode
+ :type value: :py:class:`~ska.base.control_model.AdminMode`
:raises ValueError: for unknown adminMode
"""
@@ -1186,7 +1186,7 @@ class SKABaseDevice(Device):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: DeviceStateModel
+ :type state_model: :py:class:`DeviceStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -1262,7 +1262,7 @@ class SKABaseDevice(Device):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: DeviceStateModel
+ :type state_model: :py:class:`DeviceStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -1332,7 +1332,7 @@ class SKABaseDevice(Device):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: DeviceStateModel
+ :type state_model: :py:class:`DeviceStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -1402,7 +1402,7 @@ class SKABaseDevice(Device):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: DeviceStateModel
+ :type state_model: :py:class:`DeviceStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -1472,7 +1472,7 @@ class SKABaseDevice(Device):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: DeviceStateModel
+ :type state_model: :py:class:`DeviceStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
diff --git a/src/ska/base/commands.py b/src/ska/base/commands.py
index 87b52b96..e326c62c 100644
--- a/src/ska/base/commands.py
+++ b/src/ska/base/commands.py
@@ -288,7 +288,7 @@ class ActionCommand(ResponseCommand):
:param return_code: The return_code returned by the ``do()``
method
- :type return_code: ResultCode
+ :type return_code: :py:class:`ResultCode`
"""
if return_code == ResultCode.OK:
self.succeeded()
diff --git a/src/ska/base/logger_device.py b/src/ska/base/logger_device.py
index 72f03d2c..39a57048 100644
--- a/src/ska/base/logger_device.py
+++ b/src/ska/base/logger_device.py
@@ -139,7 +139,7 @@ class SKALogger(SKABaseDevice):
* argin[0]: list of DevLong. Desired logging level.
* argin[1]: list of DevString. Desired tango device.
- :type argin: DevVarLongStringArray
+ :type argin: :py:class:`tango.DevVarLongStringArray`
:returns: None.
"""
diff --git a/src/ska/base/master_device.py b/src/ska/base/master_device.py
index bc503819..a8e0c93a 100644
--- a/src/ska/base/master_device.py
+++ b/src/ska/base/master_device.py
@@ -231,7 +231,7 @@ class SKAMaster(SKABaseDevice):
* [nrInstances]: DevLong. Number of instances of the capability.
* [Capability types]: DevString. Type of capability.
- :type argin: DevVarLongStringArray.
+ :type argin: :py:class:`tango.DevVarLongStringArray`.
:return: True if capability can be achieved, False if cannot
:rtype: DevBoolean
diff --git a/src/ska/base/obs_device.py b/src/ska/base/obs_device.py
index 9119cc0a..b92b31c2 100644
--- a/src/ska/base/obs_device.py
+++ b/src/ska/base/obs_device.py
@@ -102,7 +102,7 @@ class SKAObsDevice(SKABaseDevice):
callback
:param obs_state: the new obs_state value
- :type obs_state: ObsState
+ :type admin_mode: :py:class:`~ska.base.control_model.ObsState`
"""
self._obs_state = obs_state
self.push_change_event("obsState", obs_state)
diff --git a/src/ska/base/state_machine.py b/src/ska/base/state_machine.py
index 4096d8a1..0dc1f325 100644
--- a/src/ska/base/state_machine.py
+++ b/src/ska/base/state_machine.py
@@ -4,6 +4,9 @@ This module contains specifications of SKA state machines.
from transitions import Machine, State
+__all__ = ["OperationStateMachine", "AdminModeStateMachine", "ObservationStateMachine"]
+
+
class OperationStateMachine(Machine):
"""
State machine for operational state ("opState").
diff --git a/src/ska/base/subarray_device.py b/src/ska/base/subarray_device.py
index 949e5725..b66b16c0 100644
--- a/src/ska/base/subarray_device.py
+++ b/src/ska/base/subarray_device.py
@@ -162,7 +162,7 @@ class SKASubarrayStateModel(DeviceStateModel):
:returns: where the action is allowed in the current state:
:rtype: bool: True if the action is allowed, False if it is
- no allowed
+ not allowed
:raises StateModelError: for an unrecognised action
"""
obs_allowed = self._is_obs_action_allowed(action)
@@ -244,11 +244,11 @@ class SKASubarrayStateModel(DeviceStateModel):
OFFLINE, opState STANDBY, and obsState SCANNING).
:param op_state: the target operational state (optional)
- :type op_state: string
+ :type op_state: :py:class:`tango.DevState`
:param admin_mode: the target admin mode (optional)
- :type admin_mode: string
+ :type admin_mode: :py:class:`~ska.base.control_model.AdminMode`
:param obs_state: the target observation state (optional)
- :type obs_state: string
+ :type obs_state: :py:class:`~ska.base.control_model.ObsState`
"""
if obs_state is not None:
getattr(self._observation_state_machine, f"to_{obs_state.name}")()
@@ -384,7 +384,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel instance
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param action_hook: a hook for the command, used to build
actions that will be sent to the state model; for example,
if the hook is "scan", then success of the command will
@@ -433,7 +433,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel instance
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -476,7 +476,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel instance
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -545,7 +545,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel instance
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -601,7 +601,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -644,7 +644,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -681,7 +681,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -721,7 +721,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -760,7 +760,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -807,7 +807,7 @@ class SKASubarray(SKAObsDevice):
:param state_model: the state model that this command uses
to check that it is allowed to run, and that it drives
with actions.
- :type state_model: SKASubarrayStateModel
+ :type state_model: :py:class:`SKASubarrayStateModel`
:param logger: the logger to be used by this Command. If not
provided, then a default module logger will be used.
:type logger: a logger that implements the standard library
@@ -886,7 +886,7 @@ class SKASubarray(SKAObsDevice):
:param device: the device for which this class implements
the configure command
- :type device: SKASubarray
+ :type device: :py:class:`SKASubarray`
:param capability_types: a list strings representing
capability types.
:type capability_types: list
diff --git a/tests/conftest.py b/tests/conftest.py
index 6693cef8..0c6cc46d 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -418,7 +418,7 @@ def tango_change_event_helper(tango_context):
Event subscription callback
:param event_data: data about the change events
- :type event_data: tango.EventData
+ :type event_data: :py:class:`tango.EventData`
"""
if event_data.err:
error = event_data.errors[0]
diff --git a/tests/test_base_device.py b/tests/test_base_device.py
index f8d522aa..049b61a6 100644
--- a/tests/test_base_device.py
+++ b/tests/test_base_device.py
@@ -358,7 +358,7 @@ class TestDeviceStateModel(StateMachineTester):
:type machine: state machine object instance
:param state: the state that we are asserting to be the current
state of the state machine under test
- :type state: str
+ :type state: dict
"""
assert machine.admin_mode == state["admin_mode"]
assert machine.op_state == state["op_state"]
@@ -407,7 +407,7 @@ class TestDeviceStateModel(StateMachineTester):
:type machine: state machine object instance
:param target_state: the state that we want to get the state
machine under test into
- :type target_state: str
+ :type target_state: dict
"""
machine._straight_to_state(**target_state)
@@ -543,6 +543,8 @@ class TestSKABaseDevice(object):
# Check that we can turn off a device that is already off
tango_context.device.Off()
+ state_callback.assert_not_called()
+ status_callback.assert_not_called()
# PROTECTED REGION ID(SKABaseDevice.test_buildState_decorators) ENABLED START #
# PROTECTED REGION END # // SKABaseDevice.test_buildState_decorators
@@ -661,6 +663,10 @@ class TestSKABaseDevice(object):
assert tango_context.device.adminMode == AdminMode.ONLINE
admin_mode_callback.assert_call(AdminMode.ONLINE)
+ tango_context.device.adminMode = AdminMode.ONLINE
+ assert tango_context.device.adminMode == AdminMode.ONLINE
+ admin_mode_callback.assert_not_called()
+
# PROTECTED REGION END # // SKABaseDevice.test_adminMode
# PROTECTED REGION ID(SKABaseDevice.test_controlMode_decorators) ENABLED START #
--
GitLab