doc: multiple reStructuredText fixes

Author: David Miguel Susano Pinto

NEWS.rst

@@ -6,66 +6,78 @@ Version 0.7.0 (upcoming)
 
 * Selected most important, backwards incompatible, changes:
 
-  * The `Camera.get_trigger_type` method, deprecated on version 0.6.0,
-    has been removed as well as the multiple `TRIGGER_*` constants it
-    returned.  Use the `Camera.trigger_type` and `Camera.trigger_mode`
-    properties.  Note that, despite the similar names, the removed
-    `Camera.get_trigger_type` does not return the same as
-    `Camera.trigger_type` property.
+  * The ``Camera.get_trigger_type`` method, deprecated on version
+    0.6.0, has been removed as well as the multiple ``TRIGGER_*``
+    constants it returned.  Use the :attr:`trigger_type
+    <microscope.abc.TriggerTargetMixin.trigger_type>` and
+    :attr:`trigger_mode
+    <microscope.abc.TriggerTargetMixin.trigger_mode>` properties
+    instead.  Note that despite the similar names, the new
+    ``trigger_type`` property does not return the same as the old
+    ``get_trigger_type`` method.
 
 * Changes to device ABCs:
 
-  * The `Stage` ABC has a new method `may_move_on_enable` to hint
-    whether calling `enable` will cause the stage to move.
-
-  * All cameras had a ``"readout mode"`` setting for most cameras only
-    had a ``"default"`` value was available.  This setting has been
-    removed from the base class and is now only kept by cameras that
-    actually make use of it, namely, ``PVCamera`` and ``AndorAtmcd``.
+  * The :class:`Stage <microscope.abc.Stage>` ABC has a new
+    :meth:`may_move_on_enable
+    <microscope.abc.Stage.may_move_on_enable>` method to hint whether
+    calling :meth:`enable <microscope.abc.Device.enable>` will cause
+    the stage to move.
 
   * All cameras had ``"transform"`` setting.  This has been removed.
-    Use the ``get_transform`` and ``set_transform`` methods instead.
-    The result may be different since the ``"transform"`` setting also
+    Use the :meth:`get_transform
+    <microscope.abc.Camera.get_transform>` and :meth:`set_transform
+    <microscope.abc.Camera.set_transform>` methods instead.  The
+    result may be different since the ``"transform"`` setting also
     exposed any internal transformation after readout.
 
   * All filterwheels had a ``"position"`` setting which was redundant
     with the related get/set methods.  The setting was been removed.
 
   * New :class:`ValueLogger <microscope.abc.ValueLogger>` ABC for
-    devices with a series of sensors. Simulation and Raspberry Pi
-    implementations for MCP9808 and TSYS01 temparture sensors.
+    devices with a series of different sensors such as temperature.
 
-  * New :class:`DigitalIO <microscope.abc.DigitalIO>` ABC. Added
-    simulation device and Raspberry Pi implmentation.
+  * New :class:`DigitalIO <microscope.abc.DigitalIO>` ABC for devices
+    with a series of Digital IO (DIO) lines.
 
 * New devices supported:
 
-  * ASI MS 2000 controller (:class:`microscope.controllers.asi.ASIMS2000`)
-  
-  * RaspberryPi as a valuelogger (:class:`microscope.valuelogger.RPiValueLogger`)
-    
-  * RaspberryPi as Digital IO (:class:`microscope.digitalio.raspberrypi.RPiDIO`)
+  * ASI MS 2000 controller
+    (:class:`microscope.controllers.asi.ASIMS2000`)
+
+  * Hamamatsu cameras
+    (:class:`microscope.cameras.hamamatsu.HamamatsuCamera`)
 
-  * Hamamatsu cameras (:class:`microscope.cameras.hamamatsu.HamamatsuCamera`)
+  * Ludl MC 2000 controller
+    (:class:`microscope.controllers.ludl.LudlMC2000`)
 
-  * Ludl MC 2000 controller (:class:`microscope.controllers.ludl.LudlMC2000`)
+  * MCP9808 temperature sensor on RaspberryPi
+    (:class:`microscope.valuelogger.raspberrypi.RPiValueLogger`)
 
   * RaspberryPi camera (:class:`microscope.cameras.picamera.PiCamera`)
 
-  * Toptica iChrome MLE (:class:`microscope.controllers.toptica.iChromeMLE`)
+  * RaspberryPi as Digital IO
+    (:class:`microscope.digitalio.raspberrypi.RPiDIO`)
+
+  * Toptica iChrome MLE
+    (:class:`microscope.controllers.toptica.iChromeMLE`)
+
+  * TSYS01 temperature sensor on RaspberryPi
+    (:class:`microscope.valuelogger.raspberrypi.RPiValueLogger`)
 
 * Device specific changes:
 
-  * `PVCamera`:
+  * :class:`PVCamera <microscope.cameras.pvcam.PVCamera>`:
 
     * In version 0.6.0 the default PVCAM trigger mode was accidentally
       changed from "strobed" to "trig. first".  This has now been
       reversed.
 
     * 8-bit acquisition mode now works.
 
-  * `SimulatedCamera` now takes an optional `sensor_shape` constructor
-    argument instead of always being 512x512 pixels.
+  * :class:`SimulatedCamera <microscope.simulators.SimulatedCamera>`
+    constructor now takes an optional ``sensor_shape`` argument.
+    Previously, simulated cameras were always 512x512 pixels.
 
 * The device server logging was broken in version 0.6.0 for Windows
   and macOS (systems not using fork for multiprocessing).  This

doc/architecture/abc.rst

@@ -35,7 +35,7 @@ which defines a base interface to all devices such as the
 :meth:`shutdown <microscope.abc.Device.shutdown>` method.
 
 There is an additional special device class
-:class:`microsope.abc.DataDevice` which defines a class that has the
+:class:`microscope.abc.DataDevice` which defines a class that has the
 ability to asynchronously send data back to the calling
 connection. This is used for situations like cameras and asynchronous
 communication such as digital input signals.

doc/architecture/supported-devices.rst

@@ -71,14 +71,15 @@ Stages
 DigitalIO
 =========
 
-- Raspberry Pi (:class:`microsocpe.digitalio.raspberrypi`)
+- Raspberry Pi (:class:`microscope.digitalio.raspberrypi.RPiDIO`)
 
 
 ValueLogger
 ===========
 
-- Raspberry Pi (:class:`microsocpe.valuelogger.raspberrypi`) includes
-  support for the MCP9808 and TSYS01 I2C temperature sensors
+- Raspberry Pi
+  (:class:`microscope.valuelogger.raspberrypi.RPiValueLogger`)
+  includes support for the MCP9808 and TSYS01 I2C temperature sensors
 
 
 Other

doc/get-involved/hacking.rst

@@ -14,7 +14,7 @@ or even discussing a completely new device type.
 In short
 ========
 
-- Open new issues.  Do not create pull requests.
+- Open new issues (do not create pull requests).
 - Open a new issue even if you already have a commit made.  Even if it
   is about adding support for a new device.
 - Coding style is `Black <https://black.readthedocs.io/>`_
@@ -95,7 +95,7 @@ making a commit:
 
 .. code-block:: shell
 
-   black ./
+   black .
 
 
 Docstrings
@@ -173,4 +173,5 @@ We do not request that copyright is assigned to us, you can remain the
 copyright holder of any contribution made.  However, please ensure
 that you are the copyright holder.  Depending on your contract, even
 if you are a student, the copyright holder is likely to be your
-employer or university.  Ask your employer or PhD supervisor first.
+employer or university.  Ask your employer or PhD supervisor if you
+are not sure.

doc/install.rst

@@ -12,12 +12,11 @@ Installation
 Microscope is available on the Python Package Index (PyPI) and can be
 `installed like any other Python package
 <https://packaging.python.org/tutorials/installing-packages/>`_.  The
-short version of it is "use pip"::
+short version of it is "use pip" (you will need to have Python and pip
+already installed on your system)::
 
     python3 -m pip install microscope
 
-You need to have Python and pip already installed on your system.
-
 
 Requirements
 ============
@@ -50,11 +49,11 @@ Linux.  See the :ref:`device-server` section for details.
 Dependencies
 ============
 
-Microscope has very few dependencies.  All are Python packages
-available on PyPI and will be automatically resolved if Microscope is
+Microscope has very few dependencies and all are Python packages
+available on PyPI that will be automatically resolved if Microscope is
 installed with pip.  However, the interface to many devices is done
-via an external library (or SDK, or driver) that is only provided by
-the device vendor.
+via an external library (sometimes named SDK or driver) that is only
+provided by the device vendor.
 
 To identify if an external library is required check the device module
 documentation.  If an external library is required, contact the device

microscope/_utils.py

@@ -58,8 +58,8 @@ def library_loader(
         libname: file name or path of the library to be loaded as
             required by `dlltype`
         dlltype: the class of shared library to load.  Typically,
-            ``CDLL`` but sometimes ``WinDLL`` in windows.
-        kwargs: other arguments passed on to ``dlltype``.
+            `ctypes.CDLL` but sometimes `ctypes.WinDLL` in windows.
+        kwargs: other arguments passed on to `dlltype`.
     """
     # Python 3.8 in Windows uses an altered search path.  Their
     # reasons is security and I guess it would make sense if we

microscope/abc.py

@@ -543,15 +543,15 @@ class DataDevice(Device, metaclass=abc.ABCMeta):
     it to a client.  The client is set using set_client(uri) or (legacy)
     receiveClient(uri).
 
-    Derived classed should implement::
+    Derived classed should implement:
 
     * :meth:`abort` (required)
     * :meth:`_fetch_data` (required)
     * :meth:`_process_data` (optional)
 
-    Derived classes may override `__init__`, `enable` and `disable`,
-    but must ensure to call this class's implementations as indicated
-    in the docstrings.
+    Derived classes may override ``__init__``, ``enable`` and
+    ``disable``, but must ensure to call this class's implementations
+    as indicated in the docstrings.
 
     """
 
@@ -1705,7 +1705,7 @@ def __init__(self, numSensors: int, pullData: bool, **kwargs) -> None:
             )
         self._numSensors = numSensors
         # If pull data is True data will be pulled from the server if False
-        # data will be pushed from microsocpe (default)
+        # data will be pushed from microscope (default)
         self.pullData = pullData
 
     @abc.abstractmethod