Add HTTP API to docs

docs/Makefile

@@ -16,9 +16,9 @@ help:
 openapi: $(BUILDDIR)/swagger.yaml
 
 $(BUILDDIR)/swagger.yaml: Makefile
-	curl http://localhost:5000/api/v2/docs/swagger.yaml > $@
+	ofm-generate-openapi -o $@
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+html dirhtml singlehtml json htmlhelp epub latex latexpdf text changes xml linkcheck doctest coverage clean: openapi Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/api.rst

@@ -7,3 +7,9 @@ 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 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

docs/source/conf.py

@@ -15,12 +15,15 @@
 import os
 import sys
 
-# Load module from relative imports
+# Load module from relative imports by modifying the path
 
 module_path = os.path.abspath("../..")
 sys.path.insert(0, module_path)
 
 # Handle mock imports for non-platform-agnostic modules
+# This allows modules to load that depend on hardware that's not present, e.g.
+# the `picamera` related modules.  They won't *work* but if they load, we can
+# extract the docstrings, which is what we care about here.
 
 from unittest.mock import MagicMock
 
@@ -41,6 +44,7 @@ project = "OpenFlexure Microscope Software"
 copyright = "2018, Bath Open Instrumentation Group"  # pylint: disable=redefined-builtin
 author = "Bath Open Instrumentation Group"
 
+#TODO: extract version from ../setup.py
 # The short X.Y version
 version = ""
 # The full version, including alpha/beta/rc tags
@@ -64,9 +68,11 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.ifconfig",
-    "sphinxcontrib.httpdomain",
+    #"sphinxcontrib.httpdomain",
-    "sphinxcontrib.autohttp.flask",
+    #"sphinxcontrib.autohttp.flask",
-    "sphinxcontrib.autohttp.flaskqref",
+    #"sphinxcontrib.autohttp.flaskqref",
+    "sphinxcontrib.openapi",
+    "sphinxcontrib.redoc"
 ]
 
 # Override ordering
@@ -222,6 +228,7 @@ epub_exclude_files = ["search.html"]
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
+#TODO: update with pysangaboard?
 intersphinx_mapping = {
     "openflexure_stage": ("https://openflexure-stage.readthedocs.io/en/latest/", None),
     "picamerax": ("https://picamerax.readthedocs.io/en/latest//", None),
@@ -233,3 +240,13 @@ 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,
+    }
+]

setup.py

@@ -67,7 +67,9 @@ setup(
     # them to specific versions to enable consistent builds and testing.
     extras_require={
         "dev": [
-            "sphinxcontrib-httpdomain ~= 1.7",
+            "sphinx < 4.0", # Currently httpdomain isn't ready for 4.0
+            "sphinxcontrib-openapi ~= 0.7",
+            "sphinx_rtd_theme ~=0.5.2",
             "rope ~= 0.14.0",
             "pylint ~= 2.3",
             "pytest ~= 6.1.2",
@@ -87,6 +89,7 @@ setup(
         "console_scripts": [
             "ofm-serve=openflexure_microscope.api.app:ofm_serve",
             "ofm-rescue=openflexure_microscope.rescue.auto:main",
+            "ofm-generate-openapi=openflexure_microscope.api.app:generate_openapi"
         ]
     },
     project_urls={