Added generator tutorial

docs/_static/theme_overrides.css

@@ -44,3 +44,6 @@
     content: "▼ ";
 }
 
+.rst-content code.xref {
+    color: #236E9E;
+}

docs/conf.py

@@ -126,15 +126,19 @@ def which(name, flags=os.X_OK):
     # install it
     subprocess.call(["fc-cache", "-vf", fontdir])
 
-napoleon_use_ivar = True
+#napoleon_use_ivar = True
 
 autoclass_content = "both"
 
 autodoc_member_order = 'bysource'
 
-# If true, Sphinx will warn about all references where the target cannot be found
+# If true, Sphinx will warn about all references where the target can't be found
 nitpicky = True
 
+#The name of a reST role (builtin or Sphinx extension) to use as the default
+# role, that is, for text marked up `like this`
+default_role = "any"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -159,9 +163,10 @@ def which(name, flags=os.X_OK):
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
-intersphinx_mapping = {
-    'python': ('http://docs.python.org/2.7/', None),
-}
+intersphinx_mapping = dict(
+    python=('http://docs.python.org/2.7/', None),
+    scanpointgenerator=('http://scanpointgenerator.readthedocs.io/en/latest/',
+                        None))
 
 # -- Options for HTML output ----------------------------------------------
 

docs/developer_docs/api/controllers/managercontroller.rst

@@ -3,5 +3,11 @@ ManagerController
 
 .. module:: malcolm.controllers
 
+.. autoclass:: LayoutInfo
+    :members:
+
+.. autoclass:: OutportInfo
+    :members:
+
 .. autoclass:: ManagerController
     :members:

docs/developer_docs/api/controllers/runnablecontroller.rst

@@ -3,5 +3,8 @@ RunnableController
 
 .. module:: malcolm.controllers
 
+.. autoclass:: ParameterTweakInfo
+    :members:
+
 .. autoclass:: RunnableController
     :members:

docs/developer_docs/api/core/attribute.rst

@@ -1,22 +1,21 @@
-.. _Attribute:
-
 Attribute
 ---------
 
-An Attribute holds a value such as an Int, Float or Enum Table representing
-the current state of a block.
+.. module:: malcolm.core
+
+.. autoclass:: Attribute
+    :members:
 
-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.
+    An Attribute holds a value such as an Int, Float or Enum Table representing
+    the current state of a block.
 
-Subclasses serialize differently.
+    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.
 
-.. module:: malcolm.core
+    Subclasses serialize differently.
 
-.. autoclass:: Attribute
-    :members:

docs/developer_docs/api/core/block.rst

@@ -1,20 +1,19 @@
-.. _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.
+An object consisting of a number of Attributes and Methods.
 
 .. module:: malcolm.core
 
 .. autoclass:: Block
-    :members:
+    :members:
+
+    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.
+

docs/developer_docs/api/core/clientcomms.rst

@@ -1,11 +1,10 @@
-.. _ClientComms:
-
 ClientComms
 -----------
 
-ClientComms is used to set up communication for a client with its server
-
 .. module:: malcolm.core
 
 .. autoclass:: ClientComms
-    :members:
+    :members:
+
+    ClientComms is used to set up communication for a client with its server
+

docs/developer_docs/api/core/controller.rst

@@ -1,21 +1,19 @@
-.. _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:
+    :members:
+
+    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:

docs/developer_docs/api/core/info.rst

@@ -0,0 +1,9 @@
+Info
+====
+
+.. module:: malcolm.core
+
+.. autoclass:: Info
+    :members:
+
+    Here we will describe in a bit more information what this class does

docs/developer_docs/api/core/map.rst

@@ -1,5 +1,3 @@
-.. _Map:
-
 Map
 ---
 

docs/developer_docs/api/core/methodmeta.rst

@@ -1,17 +1,20 @@
 .. _Method:
 
-MethodMeta
-----------
+Method
+------
 
-A MethodMeta exposes a function call for a Block:
+.. module:: malcolm.core
 
-Expose a function call. You can Call a MethodMeta with a (possibly empty)
-Map of arguments, and it will return a (possibly empty) Map of return values.
-In a client Block, the Call will be forwarded to the server Block, and the
-return value returned to the caller. For example, configure() and run() would
-be Methods of a Blocks used in a mapping scan.
+.. autoclass:: MethodMeta
+    :members:
 
-.. module:: malcolm.core
+    A MethodMeta exposes a function call for a Block:
+
+    Expose a function call. You can Call a MethodMeta with a (possibly empty)
+    Map of arguments, and it will return a (possibly empty) Map of return values.
+    In a client Block, the Call will be forwarded to the server Block, and the
+    return value returned to the caller. For example, configure() and run() would
+    be Methods of a Blocks used in a mapping scan.
 
 .. data:: REQUIRED
 
@@ -21,9 +24,6 @@ be Methods of a Blocks used in a mapping scan.
 
     Used to mark an argument in method_takes() or method_returns() as optional
 
-.. autoclass:: MethodMeta
-    :members:
-
 .. autofunction:: method_takes
 
 .. autofunction:: method_returns

docs/developer_docs/api/core/part.rst

@@ -1,22 +1,21 @@
-.. _Part:
-
 Part
 ----
 
-These provide the logic for using a particular child Block with a
-particular Controller. It can register to use a number of hooks that the
-Controller provides, and the Controller will wait for all using that hook to
-run concurrently before moving to the next State. Parts can also create
-Attributes on the parent Block, as well as contribute Attributes that should
-be taken as arguments to Methods provided by the Controller. For example,
-there will be an HDFWriterPart that knows how to set PVs on the HDFWriter in
-the right order and expose the FilePath as an Attribute to the configure()
-method.
-
 A Part contains the logic for a Controller to interact with a child Block to
 perform more device-specific actions:
 
 .. module:: malcolm.core
 
 .. autoclass:: Part
-    :members:
+    :members:
+
+    These provide the logic for using a particular child Block with a
+    particular Controller. It can register to use a number of hooks that the
+    Controller provides, and the Controller will wait for all using that hook to
+    run concurrently before moving to the next State. Parts can also create
+    Attributes on the parent Block, as well as contribute Attributes that should
+    be taken as arguments to Methods provided by the Controller. For example,
+    there will be an HDFWriterPart that knows how to set PVs on the HDFWriter in
+    the right order and expose the FilePath as an Attribute to the configure()
+    method.
+

docs/developer_docs/api/core/process.rst

@@ -1,15 +1,14 @@
-.. _Process:
-
 Process
 -------
 
 A Process is a host for Block instances and allows communication between them:
 
-A Malcolm instance containing a number of Blocks along with various
-communication modules to communicate with other Malcolm instances. A Process
-can be a client of or a server to a number of other Processes.
-
 .. module:: malcolm.core
 
 .. autoclass:: Process
-    :members:
+    :members:
+
+    A Malcolm instance containing a number of Blocks along with various
+    communication modules to communicate with other Malcolm instances. A Process
+    can be a client of or a server to a number of other Processes.
+

docs/developer_docs/api/core/servercomms.rst

@@ -1,11 +1,10 @@
-.. _ServerComms:
-
 ServerComms
 -----------
 
-ServerComms is used to set up communication for a server with its clients
-
 .. module:: malcolm.core
 
 .. autoclass:: ServerComms
-    :members:
+    :members:
+
+    ServerComms is used to set up communication for a server with its clients
+

docs/developer_docs/api/core/statemachine.rst

@@ -1,16 +1,16 @@
-.. _StateMachine:
-
 StateMachine
 ------------
 
-State Machine: Every Malcolm Block contains a State Machine that maps the
-allowed transitions between different values of the State Attribute. This
-allows external applications to monitor what a Block is doing, and gives a
-condition for whether particular Methods can run or not. See the
-:ref:`statemachine` section for examples.
+.. module:: malcolm.core
 
+.. autoclass:: StateMachine
+    :members:
 
-.. module:: malcolm.core
+    State Machine: Every Malcolm Block contains a State Machine that maps the
+    allowed transitions between different values of the State Attribute. This
+    allows external applications to monitor what a Block is doing, and gives a
+    condition for whether particular Methods can run or not. See the
+    `statemachine_diagrams` section for examples.
 
 .. autoclass:: DefaultStateMachine
     :members:

docs/developer_docs/statemachine.rst

@@ -1,3 +1,5 @@
+.. _statemachine_diagrams:
+
 State Machine
 =============