Write the first tutorial in the docs restructure

dls-controls · Nov 28, 2016 · 95cd126 · 95cd126
1 parent 5b14391
commit 95cd126
Show file tree

Hide file tree

Showing 117 changed files with 674 additions and 313 deletions.
diff --git a/README.rst b/README.rst
@@ -1,7 +1,7 @@
 Malcolm
 =======
 
-|build-status| |coverage| |health| |pypi-version| |readthedocs|
+|build_status| |coverage| |health| |pypi_version| |readthedocs|
 
 Malcolm is a middlelayer service that allows high level configure/run control
 of control system components generally involved in continuous scans. This
@@ -43,15 +43,16 @@ License
 APACHE License. (see `LICENSE`_)
 
 
-.. |build-status| image:: https://travis-ci.org/dls-controls/pymalcolm.svg?style=flat
+.. |build_status| image:: https://travis-ci.org/dls-controls/pymalcolm
+.svg?style=flat
     :target: https://travis-ci.org/dls-controls/pymalcolm
     :alt: Build Status
 
 .. |coverage| image:: https://coveralls.io/repos/dls-controls/pymalcolm/badge.svg?branch=master&service=github
     :target: https://coveralls.io/github/dls-controls/pymalcolm?branch=master
     :alt: Test coverage
 
-.. |pypi-version| image:: https://img.shields.io/pypi/v/malcolm.svg
+.. |pypi_version| image:: https://img.shields.io/pypi/v/malcolm.svg
     :target: https://pypi.python.org/pypi/malcolm/
     :alt: Latest PyPI version
 

diff --git a/docs/arch/intro.rst b/docs/arch/intro.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,6 +55,7 @@ def get_version():
     'sphinxcontrib.plantuml',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
+    'IPython.sphinxext.ipython_console_highlighting',
 ]
 
 # http://twistedmatrix.com/trac/browser/tags/releases/twisted-8.2.0/twisted/python/procutils.py?format=txt

diff --git a/docs/dev/api/controllers/clientcontroller.rst b/docs/dev/api/controllers/clientcontroller.rst
diff --git a/docs/dev/api/controllers/scanpointtickercontroller.rst b/docs/dev/api/controllers/scanpointtickercontroller.rst
diff --git a/docs/dev/api/core/attribute.rst b/docs/dev/api/core/attribute.rst
diff --git a/docs/dev/api/core/block.rst b/docs/dev/api/core/block.rst
diff --git a/docs/dev/api/core/controller.rst b/docs/dev/api/core/controller.rst
diff --git a/docs/dev/api/core/map.rst b/docs/dev/api/core/map.rst
diff --git a/docs/dev/api/core/methodmeta.rst b/docs/dev/api/core/methodmeta.rst
diff --git a/docs/dev/api/core/part.rst b/docs/dev/api/core/part.rst
diff --git a/docs/dev/api/core/process.rst b/docs/dev/api/core/process.rst
diff --git a/docs/dev/api/core/statemachine.rst b/docs/dev/api/core/statemachine.rst
diff --git a/docs/dev/api/core/vmeta.rst b/docs/dev/api/core/vmeta.rst
diff --git a/.../comms/websocket/websocketclientcomms.rst → .../comms/websocket/websocketclientcomms.rst b/.../comms/websocket/websocketclientcomms.rst → .../comms/websocket/websocketclientcomms.rst
diff --git a/.../comms/websocket/websocketservercomms.rst → .../comms/websocket/websocketservercomms.rst b/.../comms/websocket/websocketservercomms.rst → .../comms/websocket/websocketservercomms.rst
diff --git a/...dev/api/controllers/defaultcontroller.rst → ...ocs/api/controllers/defaultcontroller.rst b/...dev/api/controllers/defaultcontroller.rst → ...ocs/api/controllers/defaultcontroller.rst
diff --git a/docs/developer_docs/api/controllers/managercontroller.rst b/docs/developer_docs/api/controllers/managercontroller.rst
@@ -0,0 +1,7 @@
+ManagerController
+-----------------
+
+.. module:: malcolm.controllers
+
+.. autoclass:: ManagerController
+    :members:
diff --git a/docs/developer_docs/api/controllers/runnablecontroller.rst b/docs/developer_docs/api/controllers/runnablecontroller.rst
@@ -0,0 +1,7 @@
+RunnableController
+------------------
+
+.. module:: malcolm.controllers
+
+.. autoclass:: RunnableController
+    :members:
diff --git a/docs/developer_docs/api/core/attribute.rst b/docs/developer_docs/api/core/attribute.rst
@@ -0,0 +1,22 @@
+.. _Attribute:
+
+Attribute
+---------
+
+An Attribute holds a value such as an Int, Float or Enum Table representing
+the current state of a block.
+
+Hold the current value of a piece of data of a fixed simple type
+like Int, Float, String, Enum, IntArray or Table. You can Get and Subscribe to
+changes in all Attributes, and Put to Attributes with a defined setter. In a
+client Block, Attributes will mirror the value of the Block acting as a
+server, with a Put operation being forwarded to the server Block. For example,
+the State of a Block would be an Attribute, as would the CurrentStep of a
+scan.
+
+Subclasses serialize differently.
+
+.. module:: malcolm.core
+
+.. autoclass:: Attribute
+    :members:
diff --git a/docs/developer_docs/api/core/block.rst b/docs/developer_docs/api/core/block.rst
@@ -0,0 +1,20 @@
+.. _Block:
+
+Block
+-----
+
+A Block consists of number of Attributes and Methods:
+
+An object consisting of a number of Attributes and Methods. It should
+be designed to be as small and self contained as possible, and complex logic
+should be implemented by nesting Blocks. For example, a detector driver would
+be a Block, as would an HDF writer, but there would also be a higher level
+detector Block to co-ordinate the low level Blocks. Any Block may be
+synchronized among a number of Processes, the Block acting as the server will
+perform the logic, and the client copies will expose the same API as the
+server Block to the end user.
+
+.. module:: malcolm.core
+
+.. autoclass:: Block
+    :members:
diff --git a/docs/dev/api/core/blockmeta.rst → docs/developer_docs/api/core/blockmeta.rst b/docs/dev/api/core/blockmeta.rst → docs/developer_docs/api/core/blockmeta.rst
diff --git a/docs/dev/api/core/cache.rst → docs/developer_docs/api/core/cache.rst b/docs/dev/api/core/cache.rst → docs/developer_docs/api/core/cache.rst
diff --git a/docs/dev/api/core/clientcomms.rst → docs/developer_docs/api/core/clientcomms.rst b/docs/dev/api/core/clientcomms.rst → docs/developer_docs/api/core/clientcomms.rst
@@ -1,9 +1,11 @@
+.. _ClientComms:
+
 ClientComms
 -----------
 
 ClientComms is used to set up communication for a client with its server
 
-.. module:: malcolm.core.clientcomms
+.. module:: malcolm.core
 
 .. autoclass:: ClientComms
     :members:
diff --git a/docs/developer_docs/api/core/controller.rst b/docs/developer_docs/api/core/controller.rst
@@ -0,0 +1,21 @@
+.. _Controller:
+
+Controller
+----------
+
+Controller: A State Machine just exposes the list of allowed transitions
+between States. The Controller provides the logic that goes behind those
+transitions. It creates a number of Methods fixing the external interface of
+how to control the blocks, creates some Attributes for monitoring
+configuration and runtime variables, and then exposes a number of hooks that
+Parts can utilise to be executed and control transition to other states. For
+example, there will be an AreaDetectorController with hooks for
+PreRunDriverStart, PreRunPluginStart, and Running.
+
+A Controller implements the logic for changing states and contains Hooks for
+allow Parts to run any functions that are relevant to the current transition:
+
+.. module:: malcolm.core
+
+.. autoclass:: Controller
+    :members: