Merge branch 'fix-readthedocs' into 'master'

Documentation improvements

See merge request openflexure/openflexure-microscope-server!140

.gitattributes

@@ -0,0 +1 @@
+docs/**/*.png filter=lfs diff=lfs merge=lfs -text

.gitlab-ci.yml

@@ -194,10 +194,7 @@ package:
     name: "dist"
     expire_in: 1 week
     paths:
-      - "./dist/openflexure-microscope-server-${CI_COMMIT_REF_NAME}.tar.gz"
-      - "./dist/openflexure-microscope-server-${CI_COMMIT_REF_NAME}.tar.gz.sha256"
-      - "./dist/openflexure-microscope-webapp-${CI_COMMIT_REF_NAME}.tar.gz"
-      - "./dist/openflexure-microscope-webapp-${CI_COMMIT_REF_NAME}.tar.gz.sha256"
+      - "./dist/"
 
   only:
     - master

docs/Makefile

@@ -20,5 +20,5 @@ $(BUILDDIR)/swagger.yaml: Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: openapi Makefile
+html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -1,2 +1,9 @@
-sphinxcontrib.httpdomain
-sphinx_rtd_theme
+sphinx_rtd_theme
+numpy
+labthings
+expiringdict
+sangaboard
+typing_extensions
+pillow
+piexif
+python-dateutil

docs/source/api.rst

@@ -6,10 +6,7 @@ Live documentation
 
 Full, interactive Swagger documentation for your microscopes web API is available from the microscope itself. From any browser, go to ``http://{your microscope IP address}/api/v2/docs/swagger-ui``.
 
-.. note:: We should have an online copy of the API SwaggerUI documentation up soon.
+The API is described in an OpenAPI description, available at ``http://{your microscope IP address}/api/v2/docs/openapi.yaml``.  It is also available from our `build server`_.  It can be conveniently viewed using `Redoc's online preview`_.
 
-The API is now also detailed below, or there is a more interactive version of the docs statically compiled using ReDoc_
-
-.. openapi:: ../build/swagger.yaml
-
-.. _ReDoc: api_redoc.html
+.. _`build server`: https://build.openflexure.org/openflexure-microscope-server/
+.. _`Redoc's online preview`: https://redocly.github.io/redoc/?url=https://build.openflexure.org/openflexure-microscope-server/latest-api.yaml

docs/source/conf.py

@@ -15,6 +15,22 @@
 import os
 import sys
 
+# Workaround to install and execute git-lfs on Read the Docs
+if os.system("git lfs env > /dev/null") == 0:
+    os.system("git lfs fetch")
+    os.system("git lfs checkout")
+else:
+    print(
+        "Warning: it seems git lfs is not installed.  Bodging our way around the problem to retrieve images..."
+    )
+    os.system(
+        "wget https://github.com/git-lfs/git-lfs/releases/download/v2.7.1/git-lfs-linux-amd64-v2.7.1.tar.gz"
+    )
+    os.system("tar xvfz git-lfs-linux-amd64-v2.7.1.tar.gz")
+    os.system("./git-lfs install")  # make lfs available in current repository
+    os.system("./git-lfs fetch")  # download content from remote
+    os.system("./git-lfs checkout")  # make local files to have the real content on them
+
 # Load module from relative imports by modifying the path
 
 module_path = os.path.abspath("../..")
@@ -68,8 +84,6 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.ifconfig",
-    "sphinxcontrib.openapi",
-    "sphinxcontrib.redoc",
 ]
 
 # Override ordering
@@ -237,13 +251,3 @@ intersphinx_mapping = {
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
-
-# -- Options for redoc extension ---------------------------------------------
-redoc = [
-    {
-        "name": "OpenFlexure Microscope HTTP API",
-        "page": "api_redoc",
-        "spec": "../build/swagger.yaml",
-        "embed": True,
-    }
-]

docs/source/index.rst

@@ -6,6 +6,7 @@ Welcome to OpenFlexure Microscope Software's documentation!
    :caption: Contents:
 
    quickstart.rst
+   webapp/index.rst
    config.rst
    microscope.rst
    camera.rst

docs/source/quickstart.rst

@@ -6,17 +6,21 @@ Install
 
 Stable installation
 +++++++++++++++++++
-For most users, the OpenFlexure Microscope software should be installed using our `pre-built Raspbian SD card image. <https://openflexure.org/projects/microscope/install>`_
+The OpenFlexure Microscope software is designed to be run on the embedded Raspberry Pi, in an OpenFlexure Microscope.  For most users, our `pre-built Raspbian SD card image. <https://openflexure.org/projects/microscope/install>`_ is the easiest way to get started.  This SD card image is based on Raspberry Pi OS and includes both the microscope server and OpenFlexure Connect.  A desktop shortcut will directly start OpenFlexure Connect if you are using the Raspberry Pi directly, or the microscope can be controlled over the network with its default hostname `raspberrypi.local`.
 
 
 Manual installation
 +++++++++++++++++++
 
-For offline (i.e. no real microscope connected) development, a basic development server can run on any system.
+To install the server on a Raspberry Pi without using the pre-built OpenFlexure Raspbian image, or to install the server on a different system (this is useful for development), follow the instructions in the README file at the top level of the project's repository.
 
-- (Recommended) create and activate a virtual environment
-- Install non-python dependencies with ``sudo apt-get install libatlas-base-dev libjasper-dev libjpeg-dev``
-- Install `Poetry <https://github.com/sdispater/poetry>`_, clone this repo, and ``poetry install`` from inside the repo.
+Usage
+-----
+The easiest way to use the microscope is through OpenFlexure Connect, our cross-platform application that handles discovering and connecting to the microscope.  It is detailed on the `instruction page on our website <https://openflexure.org/projects/microscope/control>`_ including a download link.  OpenFlexure Connect is pre-installed on the full SD card image (not the "lite" image, as this does not have support for a graphical desktop).
+
+If you know the hostname or IP address of your microscope, you can also connect to the same interface using a web browser by entering `http://microscope.local:5000/` as the address.  `microscope.local` is the default hostname of the microscope if you use our pre-built SD card image.  If you know the IP address or have customised the hostname, you can use that instead.  Note that the hostname is announced via mDNS, which is usually reliable if the microscope is connected via a network cable directly to your client computer but may not work if both devices are connected to a more complicated network.  As support for mDNS varies between operating systems, OpenFlexure Connect often detects microscopes even if you cannot resolve the microscope using the mDNS hostname.
+
+Whether you connect with OpenFlexure Connect, or through a web browser, the web application interface is the same.  See the "web application" section of this manual for more details.
 
 Managing the server
 -------------------

docs/source/webapp/index.rst

@@ -0,0 +1,22 @@
+Web Application interface
+=========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   pane_navigate
+   pane_capture
+   pane_settings
+   pane_gallery
+
+The main graphical interface for the OpenFlexure Microscope is implemented as a web application, which allows it to be accessed either through OpenFlexure Connect or a web browser.  See the :doc:`../quickstart` page for connection instructions.  A "tour" should guide users through the interface when they connect for the first time, and introduce the key interface elements.  
+
+Interface structure
+-------------------
+The main interface has a tab bar on the left, which allows the operator to select different controls.  By default, the "view" pane does not show any additional controls, and a video feed from the camera fills the window.
+
+.. image:: pane_view.png
+
+Selecting one of the tab icons on the left will bring up the corresponding interface.  Most of the pages display the image on the right hand side, and add additional controls between the image display and the tab bar.
+

docs/source/webapp/pane_capture.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0dcbbfbc4d5ba77824083b497b015b4178ec47f375f8e0457cb103da5befd2cf
+size 1971891

docs/source/webapp/pane_capture.rst

@@ -0,0 +1,23 @@
+Capture pane
+============
+The capture pane allows images to be acquired through the interface.  By default, a single image is captured to the microscope's internal SD card, and can be downloaded from the gallery.  Various settings are available to control the resolution of the image captured: the "full resolution" checkbox will save the image at native resolution, and the "store raw data" checkbox saves raw pixel data as an EXIF annotation.  
+
+Due to the underlying ``picamera`` library, images are always saved as JPEG files, and raw data is simply appended to the file for later extraction.  If an image is saved with raw data, the JPEG image is still the processed, compressed version; an external tool must be used to extract and process the raw Bayer data.
+
+.. image:: pane_capture.png
+
+It is also possible to acquire a grid of images for stitching together into a mosaic, by expanding the "Stack and Scan" section and enabling the "Scan capture" checkbox.  Scans are 3D by default (i.e. a mosaic of images in X and Y, with a Z stack at each position) but 2D or linear scans can be performed by setting the number of steps in the unused axes to 1.  This allows XY mosaics or Z stacks to be performed.  
+
+When scanning is enabled, the "capture" button is replaced by a "start scan" button, which will start the scan and display a progress indicator until scanning has finished.
+
+.. image:: scan_dialog.png
+
+The step sizes (in motor steps) for each axis specify the number of motor steps to move between images, then the "steps" fields specify the number of images to acquire along each axis.  If "steps" is set to 1 for any axis, no scanning happens along that axis.
+
+The scan routine will move through XY coordinates, and at each XY position will optionally run an autofocus routine, then acquire either a single image or a Z stack depending on the value of "z steps".  The autofocus options correspond to those available in the "move" pane, allowing "fast" autofocus, or conventional autofocus with coarse, medium, or fine steps to be used.  Selecting "none" disables autofocus.  The vast majority of the time, "fast" autofocus is both quicker and more accurate than the other methods.
+
+Various scan patterns are available for XY scanning.  Raster scanning is the default, which scans columns (i.e. from lowest to highest Y coordinate) and works from low to high X coordinates as the "slow" scan axis.  Snake scanning reverses every other column, such that there is a smaller distance from the end of one column to the beginning of the next.  This can be helpful if the sample is not perfectly flat, as it avoids losing focus between columns.  Finally, "spiral" scanning starts by taking an image at the current position, then works outwards in concentric squares.  Spiral scans use the "x steps" value to set the number of rings, and ignore the "y steps" value.
+
+Images acquired during the scan will be saved to a folder on the Raspberry Pi.  They can be named according to their coordinates in the scan (default) or numbered sequentially (in case the latter is easier to process).
+
+To retrieve images acquired during a scan, or captured individually, you can use the :doc:`pane_gallery`.

docs/source/webapp/pane_gallery.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4c5dc30ff335f782d9a5c9d5568e13787f63be7e5d0a46c73afd5d525e79d557
+size 1370769

docs/source/webapp/pane_gallery.rst

@@ -0,0 +1,10 @@
+Gallery pane
+============
+
+.. image:: pane_gallery.png
+
+The gallery displays all the images currently stored on the microscope.  Scans are grouped together into folders.  Clicking on an image will display it in a "lightbox" view that allows scrolling through all images in the current view.  When an image is displayed in the lightbox view, it may be right-clicked to download it.  Multiple images can also be downloaded as a zip archive.
+
+Bulk transfer of images is often easier using SCP, and images are stored by default in ``/var/openflexure/data/micrographs/`` on the Raspberry Pi.
+
+Saving of images to external storage is possible - this can be configured using the "autostorage" plugin, which currently displays an SD card icon in the navigation bar at the left of the screen.

docs/source/webapp/pane_navigate.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:400d4f25aef0fecddbab296d982fb881367f1c5b6cdbd83b592bbbd142f3ef04
+size 3184560

docs/source/webapp/pane_navigate.rst

@@ -0,0 +1,10 @@
+Navigate pane
+=============
+
+The navigate pane displays the current stage position.  Editing the values for X, Y, and Z and then hitting "enter" or clicking "move" will move the stage to the specified coordinates.  Using the arrow keys (or page up/down) when not editing a text box will also move the stage, and the step size used can be set in the "configure" section at the top of the pane (which is collapsed by default).  Using the mouse scroll wheel on the image will also move in Z, using the same configured step size. Double clicking on the image will bring the point clicked to the centre of the field of view, if the camera-stage mapping has been calibrated (see :doc:`pane_settings`).
+
+Autofocus can also be run from the navigate pane, by clicking the "fast", "medium" or "fine" buttons.  Fast autofocus moves the stage up and down in a continuous motion, using the size of images in the MJPEG stream from the camera to determine the sharpest point.  This is usually both faster and more accurate than the other methods, however the other two options use a different metric, and stop the stage for each measurement.  This can lead to them being more reliable in some circumstances.
+
+.. image:: pane_navigate.png
+
+

docs/source/webapp/pane_settings.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ac21613d68c30c3e9038f71d738d41a266e6d99f3f93c9b92f833f1564ccd179
+size 668472

docs/source/webapp/pane_settings.rst

@@ -0,0 +1,14 @@
+Settings pane
+=============
+
+The settings for the microscope are gathered together into a settings pane, which is further subdivided into sections.  This page does not provide an exhaustive list, but a few of the notable controls are:
+
+* Adjusting exposure time and gain of the camera, including automatic adjustment.
+* Automatic white balance and flat-field correction for the camera.
+* Enabling or disabling certain features of the software (e.g. ImJoy integration).
+* Enabling or disabling the video stream (this allows the native low-latency preview on the Raspberry Pi to be used instead).
+* Calibrating the relationship between stage coordinates and pixel coordinates in the video stream, allowing click-to-move to function.
+
+Important calibration tasks (in particular camera settings adjustment and click-to-move calibration) will be prompted in a "wizard" dialogue when the software is first run, to help first time users set up their microscope.  All of the auto calibration routines are also available from the settings pane.
+
+.. image:: pane_settings.png

docs/source/webapp/pane_view.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aca1cddcdd8038920748196f95307d8d0110ed702990dd4831b1566afe01dabd
+size 1930201

docs/source/webapp/scan_dialog.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5bc4944c89be5f43b178145fc7ff8c414dac1716275dc83e02a4bc23493aa2fb
+size 32284