From d681a2069d863675476a918298e9d3c44c307e89 Mon Sep 17 00:00:00 2001
From: Joel Collins <joel@jtcollins.net>
Date: Thu, 20 Dec 2018 11:31:50 +0000
Subject: [PATCH] Started re-writing plugin documentation

---
 docs/source/camera.rst                        |  1 -
 docs/source/pluginmounts.rst                  | 17 ++++++++++
 docs/source/plugins.rst                       | 32 ++++++++++++++-----
 .../microscoperc.default.yaml                 |  3 +-
 openflexure_microscope/plugins/default/api.py | 14 ++++++--
 .../plugins/test_plugin/__init__.py           |  1 -
 .../plugins/test_plugin/plugin.py             | 14 --------
 7 files changed, 54 insertions(+), 28 deletions(-)
 create mode 100644 docs/source/pluginmounts.rst
 delete mode 100644 openflexure_microscope/plugins/test_plugin/__init__.py
 delete mode 100644 openflexure_microscope/plugins/test_plugin/plugin.py

diff --git a/docs/source/camera.rst b/docs/source/camera.rst
index c14dd770..b3506cd2 100644
--- a/docs/source/camera.rst
+++ b/docs/source/camera.rst
@@ -3,7 +3,6 @@ Camera Functionality
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
    picamera.rst
    basecamera.rst
diff --git a/docs/source/pluginmounts.rst b/docs/source/pluginmounts.rst
new file mode 100644
index 00000000..ba8b5bb8
--- /dev/null
+++ b/docs/source/pluginmounts.rst
@@ -0,0 +1,17 @@
+Plugin mounts
+===============
+.. automodule:: openflexure_microscope.plugins
+    :members:
+
+Default plugins
+===============
+
+Microscope plugin
++++++++++++++++++
+.. automodule:: openflexure_microscope.plugins.default.plugin
+    :members:
+
+Web API plugin
+++++++++++++++
+.. automodule:: openflexure_microscope.plugins.default.api
+    :members:
diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst
index bd8a29b9..43d7805f 100644
--- a/docs/source/plugins.rst
+++ b/docs/source/plugins.rst
@@ -1,11 +1,27 @@
-Plugin System
-=============
+Plugins
+=======================================================
 
-.. automodule:: openflexure_microscope.plugins
-    :members:
+Introduction
+------------
 
-Example Plugin
---------------
+Single-file plugins
++++++++++++++++++++
 
-.. automodule:: openflexure_microscope.plugins.default.test_plugin
-    :members:
\ No newline at end of file
+Package plugins
++++++++++++++++
+
+Loading plugins with microscoperc.yaml
+++++++++++++++++++++++++++++++++++++++
+
+Microscope plugin structure
+---------------------------
+
+Adding web API routes
+---------------------
+
+Mounting and built-ins
+----------------------
+.. toctree::
+   :maxdepth: 2
+
+   pluginmounts.rst
\ No newline at end of file
diff --git a/openflexure_microscope/microscoperc.default.yaml b/openflexure_microscope/microscoperc.default.yaml
index 4e1f515e..3c10e6ce 100644
--- a/openflexure_microscope/microscoperc.default.yaml
+++ b/openflexure_microscope/microscoperc.default.yaml
@@ -22,5 +22,4 @@ picamera_params:
 
 # Default plugins
 plugins:
-  - openflexure_microscope.plugins.default:Plugin
-  - openflexure_microscope.plugins.test_plugin:FirstPlugin
\ No newline at end of file
+  - openflexure_microscope.plugins.default:Plugin
\ No newline at end of file
diff --git a/openflexure_microscope/plugins/default/api.py b/openflexure_microscope/plugins/default/api.py
index fce53194..ca0ce594 100644
--- a/openflexure_microscope/plugins/default/api.py
+++ b/openflexure_microscope/plugins/default/api.py
@@ -7,14 +7,24 @@ import logging
 
 
 class IdentifyAPI(MicroscopeViewPlugin):
-
+    """
+    A simple example API plugin, attached through the main microscope plugin.
+    """
     def get(self):
+        """
+        Method to call when an HTTP GET request is made.
+        """
         data = self.microscope.plugin.default.identify()  # Call a method from our plugin, using the full route
         return Response(escape(data))
 
 
 class HelloWorldAPI(MicroscopeViewPlugin):
-
+    """
+    An even simpler example API plugin, which just returns static data without using the microscope.
+    """
     def get(self):
+        """
+        Method to call when an HTTP GET request is made.
+        """
         data = self.plugin.hello_world()  # Call a method from our plugin, using the MicroscopeViewPlugin.plugin shortcut
         return Response(data)
diff --git a/openflexure_microscope/plugins/test_plugin/__init__.py b/openflexure_microscope/plugins/test_plugin/__init__.py
deleted file mode 100644
index 44d6fa90..00000000
--- a/openflexure_microscope/plugins/test_plugin/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-from .plugin import FirstPlugin
\ No newline at end of file
diff --git a/openflexure_microscope/plugins/test_plugin/plugin.py b/openflexure_microscope/plugins/test_plugin/plugin.py
deleted file mode 100644
index e6bf90ab..00000000
--- a/openflexure_microscope/plugins/test_plugin/plugin.py
+++ /dev/null
@@ -1,14 +0,0 @@
-from openflexure_microscope.plugins import MicroscopePlugin
-
-
-class FirstPlugin(MicroscopePlugin):
-    """
-    An example Microscope plugin. 
-    """
-    def run(self):
-        """
-        Demonstrate access to Microscope.camera, and Microscope.stage
-        """
-
-        response = "My parent camera is {}, and my parent stage is {}.".format(self.microscope.camera, self.microscope.stage)
-        return response
\ No newline at end of file