Finish publish ioc and use asyncio pages.

Add a docstring to AsyncioDispatcher.__init__ to suppress the docstring from threading.Thread, which is misleading.

Author: AlexanderWells-diamond

docs/conf.py

@@ -96,6 +96,7 @@
 intersphinx_mapping = dict(
     python=('https://docs.python.org/3/', None),
     cothread=("https://cothread.readthedocs.org/en/stable/", None),
+    aioca=("https://dls-controls.github.io/aioca/master/", None),
     epicsdbbuilder=(
         "https://dls-controls.github.io/epicsdbbuilder/master/", None)
 )

docs/examples/example_asyncio_ioc.py

@@ -1,6 +1,5 @@
 # Import the basic framework components.
 from softioc import softioc, builder, asyncio_dispatcher
-from aioca import caget, caput
 import asyncio
 
 # Create an asyncio dispatcher, the event loop is now running

docs/how-to/make-publishable-ioc.rst

@@ -1,65 +1,35 @@
 Create a Publishable IOC
---------------------------
+========================
 
-As the example script above shows, a single Python script can be an IOC.
-However, to fit into the DLS framework for publishing IOCs in ``/dls_sw/prod`` a
-bit more structure is needed.  I recommend at least four files as shown:
+As seen in :doc:`../tutorials/creating-an-ioc`, a single Python script can be an IOC.
+It is also possible (and the most common situation) to have an entire Python module
+comprising an IOC. This guide explains both, as well as how to publish an IOC within
+the DLS environment.
 
-``Makefile``
-    This file is necessary in order to run ``dls-release.py``, and needs to have
-    both ``install`` and ``clean`` targets, but doesn't need to actually do
-    anything.  Thus the following content for this file is enough::
-
-        install:
-        clean:
-
-``start-ioc``
-    An executable file for starting the IOC needs to be created.  I recommend
-    that this consist of the following boilerplate::
-
-        #!/bin/sh
-
-        PYIOC_VER=2-6
-        EPICS_VER=3.14.12.3
-
-        PYIOC=/dls_sw/prod/R$EPICS_VER/support/pythonSoftIoc/$PYIOC_VER/pythonIoc
+Single File IOC
+----------------
+An IOC that is entirely contained within a single Python source file can be used as an 
+IOC inside DLS simply by adding this shebang line::
 
-        exec $PYIOC ioc_entry.py "$@"
+    #!/dls_sw/prod/python3/RHEL7-x86_64/pythonIoc/prefix/bin/pythonIoc
 
-    Here I have given the startup script for the IOC the name ``ioc_entry.py``.
-    This name should be replaced by any appropriate name.
 
-``ioc_entry.py``
-    I recommend that the top level Python script used to launch the IOC contain
-    only ``pkg_resources.require`` statements, simple code to start the body
-    of the IOC, and it should end with standard code to start the IOC.  The
-    following structure can be followed (here I've assumed that the rest of the
-    IOC is in a single file called ``ioc_body.py``::
+IOC entry point for a module
+------------------------------
+If your IOC is more complicated than one file, it is recommended to write a python 
+module (including docs/tests/etc.). The Panda Blocks Client will be an example of
+this.
 
-        from pkg_resources import require
 
-        require('cothread==2.12')
-        require('epicsdbbuilder==1.0')
-        # Any other requires needed by this IOC
+Make an IOC publishable at DLS
+------------------------------
+To make the IOC publishable, a makefile is required:
 
-        from softioc import softioc
-
-        # Do whatever makes sense to create all the PVs and get ready to go
-        import ioc_body
-        ioc_body.initialise()
-
-        # Start the IOC -- this is boilerplate
-        builder.LoadDatabase()
-        softioc.iocInit()
-
-        # If activities need to be started after iocInit, now's the time
-        ioc_body.start()
-
-        softioc.interactive_ioc(globals())
+``Makefile``
+    This file is necessary in order to run ``dls-release.py``, and needs to have
+    both ``install`` and ``clean`` targets, but doesn't need to actually do
+    anything.  Thus the following content for this file is enough::
 
-    Note that *all* requires *must* occur in this initial startup file.
+        install:
+        clean:
 
-The rest of the IOC
-    Of course, a Python script can be structured into any number of Python
-    modules.  In the example above I have illustrated just one such module
-    called ``ioc_body.py`` with two entry points.

docs/how-to/use-asyncio-in-an-ioc.rst

@@ -1,4 +1,32 @@
 Use `asyncio` in an IOC
 =======================
 
-Write about the differences creating an IOC using `AsyncioDispatcher`
+There are two libraries available for asynchronous operations in PythonIOC:
+:mod:`cothread` and :mod:`asyncio`. This guide shows how to use the latter in
+an IOC.
+
+.. note::
+    This page only explains the differences between using :mod:`cothread` and :mod:`asyncio`.
+    For more thorough explanation of the IOC itself see :doc:`../tutorials/creating-an-ioc`
+
+.. literalinclude:: ../examples/example_asyncio_ioc.py
+
+
+The ``dispatcher`` is created and passed to :func:`~softioc.softioc.iocInit`. This is what 
+allows the use of :mod:`asyncio` functions in this IOC.
+
+The ``async update`` function will increment the value of ``ai`` once per second,
+sleeping that coroutine between updates.
+Note that we run this coroutine in the ``loop`` of the ``dispatcher``, and not in the
+main event loop.
+
+This IOC will, like the one in :doc:`../tutorials/creating-an-ioc`, leave an interactive 
+shell open. The values of the PVs can be queried using the methods defined in the 
+:mod:`softioc.softioc` module.
+
+
+Asynchronous Channel Access
+---------------------------
+
+PVs can be retrieved in an asynchronous manner by using the :py:mod:`aioca` module. 
+It provides ``await``-able implementations of ``caget``, ``caput``, etc.

softioc/asyncio_dispatcher.py

@@ -9,6 +9,9 @@ class AsyncioDispatcher(threading.Thread):
     created.
     """
     def __init__(self):
+        """Create the AsyncioDispatcher."""
+        # Docstring specified to suppress threading.Thread's docstring, which
+        # would otherwise be inherited by this method and be misleading.
         super().__init__()
         #: `asyncio` event loop that the callbacks will run under.
         self.loop = asyncio.new_event_loop()