doc: multiple fixes on reST syntax, link more docs, remove design.rst

wip fixes on Rest syntax

Author: carandraug

NEWS.rst

@@ -24,7 +24,7 @@ Version 0.7.0 (upcoming)
 
   * Ludl MC 2000 (:class:`microscope.controllers.ludl.LudlMC2000`)
 
-  * Raspberry Pi picam (:class:`microscope.cameras.picam.Picamera`)
+  * Raspberry Pi picam (:class:`microscope.cameras.picam.PiCamera`)
 
   * Toptica iChrome MLE (:class:`microscope.controllers.toptica.iChromeMLE`)
 

doc/architecture/abc.rst

@@ -93,8 +93,8 @@ few reasons not to.  First, many classes support a wide range of
 models, for example, ``AndorSDK3`` supports all of Andor CMOS cameras,
 and different models have different settings which would lead to
 multiple classes with different sets of methods.  Second, some of
-those settings would clash with the ABC, for example, `"AndorAtmcd"`
-devices might have a `"Binning"` setting which could clash with the
+those settings would clash with the ABC, for example, ``AndorAtmcd``
+devices might have a ``"Binning"`` setting which could clash with the
 ``binning`` property.  Finally, using ``get_setting`` and
 ``set_setting`` clearly declares the use of methods that are not part
 of the interface and reminds the implications that come with it.

doc/architecture/device-server.rst

@@ -35,18 +35,18 @@ series of advantages:
 
    add figures to explain device server (figure from the paper).
 
-The `device-server` program
-===========================
+The ``device-server`` program
+=============================
 
-The `device-server` program is part of the Microscope installation.
+The ``device-server`` program is part of the Microscope installation.
 It can started from the command line with a configuration file
 defining the devices to be served, like so:
 
 .. code-block:: bash
 
     device-server PATH-TO-CONFIGURATION-FILE
     # alternatively, if scripts were not installed:
-    python -m microscope.device_server PATH-TO-CONFIGURATION-FILE
+    python3 -m microscope.device_server PATH-TO-CONFIGURATION-FILE
 
 where the configuration file is a Python script that declares the
 devices to be constructed and served on its ``DEVICES`` attribute via
@@ -123,7 +123,7 @@ matter of knowing the device server URI:
 
     import Pyro4
 
-    proxy = Pyro4.Proxy('PYRO:SomeLaser@127.0.0.1:8000')
+    proxy = Pyro4.Proxy("PYRO:SomeLaser@127.0.0.1:8000")
     # use proxy as if it was an instance of the SomeLaser class
     proxy._pyroRelease()
 
@@ -135,9 +135,9 @@ devices it controls.
 Pyro configuration
 ------------------
 
-Pyro4 configuration is the singleton :obj:`Pyro4.config`.  If there's
-any special configuration wanted, this can be done on the
-`device-server` configuration file:
+Pyro4 configuration is the singleton ``Pyro4.config``.  If there's any
+special configuration wanted, this can be done on the
+``device-server`` configuration file:
 
 .. code-block:: python
 
@@ -155,7 +155,7 @@ any special configuration wanted, this can be done on the
         #...
     ]
 
-Importing the `microscope.device_server` will already change the Pyro
+Importing ``microscope.device_server`` will already change the Pyro
 configuration, namely it sets the `SERIALIZER` to use the pickle
 protocol.  Despite the security implications associated with it,
 pickle is the fastest of the protocols and one of the few capable of
@@ -170,10 +170,10 @@ device that can't be specified during object construction, and only
 after initialisation can it be identified.  This happens in some
 cameras and is an issue when more than one such device is present.
 For example, if there are two Andor CMOS cameras present, it is not
-possible to specify which one to use when constructing the `AndorSDK3`
-instance.  Only after the device has been initialised can we query its
-ID, typically the device serial number, and check if we obtained the
-one we want.  Like so:
+possible to specify which one to use when constructing the
+``AndorSDK3`` instance.  Only after the device has been initialised
+can we query its ID, typically the device serial number, and check if
+we obtained the one we want.  Like so:
 
 .. code-block:: python
 
@@ -190,7 +190,7 @@ one we want.  Like so:
 
 In the interest of keeping each camera on their own separate process,
 the above can't be used.  To address this, the device definition must
-specify the `uid` if the device class is a floating device.  Like so::
+specify ``uid`` if the device class is a floating device.  Like so::
 
     DEVICES = [
         device(AndorSDK3, "127.0.0.1", 8000, uid="20200910"),
@@ -199,8 +199,8 @@ specify the `uid` if the device class is a floating device.  Like so::
 
 The device server will then construct each device on its own process,
 and then serve them on the named port.  Two implication come out of
-this.  The first is that the `uid` *must* be specified, even if there
-is only such device present on the system.  The second is that all
+this.  The first is that ``uid`` *must* be specified, even if there is
+only such device present on the system.  The second is that all
 devices of that class *must* be present.
 
 .. _composite-devices:
@@ -211,11 +211,11 @@ Composite Devices
 A composite device is a device that internally makes use of another
 device to function.  These are typically not real hardware, they are
 an abstraction that merges multiple devices to provide something
-augmented.  For example, `ClarityCamera` is a camera that returns a
-processed image based on the settings of `AuroxClarity`.  Another
-example is the `StageAwareCamera` which is a dummy camera that returns
-a subsection of an image file based on the stage coordinates in order
-to mimic navigating a real sample.
+augmented.  For example, ``ClarityCamera`` is a camera that returns a
+processed image based on the settings of ``AuroxClarity``.  Another
+example is the ``StageAwareCamera`` which is a dummy camera that
+returns a subsection of an image file based on the stage coordinates
+in order to mimic navigating a real sample.
 
 If the multiple devices are on the same computer, it might be worth
 have them share the same process to avoid the inter process

doc/architecture/gui.rst

@@ -19,7 +19,7 @@ Still, during development, both of the microscope and support for new
 modules, a GUI can be useful.  For example, check what a camera is
 acquiring, emitting light, checking if all methods are working as
 expected.  For this purpose, there is the ``microscope-gui`` program
-as well as a :mod:``microscope.gui`` module with Qt widgets.
+as well as a :mod:`microscope.gui` module with Qt widgets.
 
 The ``microscope-gui`` program provides a minimal GUI for each device
 type.  It requires the device server.  For example:

doc/architecture/settings.rst

@@ -16,19 +16,21 @@ Cameras
 =======
 
 - Andor (:class:`microscope.cameras.andorsdk3.AndorSDK3` and
-  :class:`microscope.cameras.atmcd.AndotAtmcd`)
+  :class:`microscope.cameras.atmcd.AndorAtmcd`)
 - Hamamatsu (:class:`microscope.cameras.hamamatsu.HamamatsuCamera`)
 - Photometrics (:class:`microscope.cameras.pvcam.PVCamera`)
 - QImaging (:class:`microscope.cameras.pvcam.PVCamera`)
+- Raspberry Pi camera (:class:`microscope.cameras.picam.PiCamera`)
 - Ximea (:class:`microscope.cameras.ximea.XimeaCamera`)
 
 Controllers
 ===========
 
 - CoolLED (:class:`microscope.controllers.coolled.CoolLED`)
-- Prior ProScan III (:class:`microscope.controllers.prior.ProScanIII`)
+- Ludl MC 2000 (:class:`microscope.controllers.ludl.LudlMC2000`)
 - Lumencor Spectra III light engine
   (:class:`microscope.controllers.lumencor.SpectraIIILightEngine`)
+- Prior ProScan III (:class:`microscope.controllers.prior.ProScanIII`)
 - Toptica iChrome MLE (:class:`microscope.controllers.toptica.iChromeMLE`)
 - Zaber daisy chain devices
   (:class:`microscope.controllers.zaber.ZaberDaisyChain`)
@@ -61,6 +63,8 @@ Light Sources
 Stages
 ======
 
+- Linkam CMS196 (:class:`microscope.stages.linkam.LinkamCMS`)
+- Ludl (:class:`microscope.controllers.ludl.LudlMC2000`)
 - Zaber (:class:`microscope.controllers.zaber.ZaberDaisyChain`)
 
 Other

doc/architecture/supported-devices.rst

@@ -10,9 +10,12 @@ Contributors
 The following people have contributed in the development of
 Microscope:
 
+- Danail Stoychev
 - David Miguel Susano Pinto
 - Ian Dobbie
 - Julio Mateos-Langerak
 - Mick Phillips
+- Nicholas Hall
+- Thomas Fish
 - Tiago Susano Pinto
 - 久保俊貴 (Toshiki Kubo)

doc/authors.rst

@@ -17,43 +17,57 @@
 
 # This should ve read from setup.py.  Maybe we should use
 # pkg_resources to avoid duplication?
-author = "Micron Oxford"
+author = ""
 project = "Microscope"
 
 copyright = "%s, %s" % (datetime.datetime.now().year, author)
 
 master_doc = "index"
-nitpicky = True
+# nitpicky = True
 
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
 ]
 
+# Configuration for sphinx.ext.autodoc
 autodoc_mock_imports = [
-    # "microscope._wrappers",
+    "microscope._wrappers",
+    "microscope.cameras._SDK3",  # should go into microscope._wrappers
     "picamera",
     "picamera.array",
-    "RPi"
+    "RPi",
+    "servicemanager",
+    "win32service",
+    "win32serviceutil",
 ]
 
-# Configuration for sphinx.ext.todo
-todo_include_todos = True
+# Configuration for sphinx.ext.intersphinx
+intersphinx_mapping = {
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pyro4": ("https://pyro4.readthedocs.io/en/stable/", None),
+    "pyserial": ("https://pyserial.readthedocs.io/en/latest/", None),
+    "python": ("https://docs.python.org/3", None),
+}
 
 # Configuration for sphinx.ext.napoleon
 napoleon_google_docstring = True
 napoleon_include_private_with_doc = True
-napoleon_include_special_with_doc = True
+napoleon_include_special_with_doc = False
+
+# Configuration for sphinx.ext.todo
+todo_include_todos = True
 
 
 #
 # Options for HTML output
 #
 
-html_theme = "agogo"
+# html_theme = "agogo"
 html_static_path = ["_static"]
 html_title = "Python Microscope documentation"
 html_short_title = "import microscope"