api: document exceptions (#680)

Author: oliver-sanders

src/conf.py

@@ -37,6 +37,8 @@
     'sphinx.ext.doctest',
     'sphinx.ext.graphviz',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
     'sphinxcontrib.spelling',
     # sphinx user community extensions
     'hieroglyph',
@@ -130,7 +132,10 @@
 nitpick_ignore = [
     # This class appears in documented type-hints but is not documented in the
     # Python docs so fails build.
-    ('py:class', 're.Pattern')
+    ('py:class', 're.Pattern'),
+    ('py:class', 'SubFuncContext'),
+    ('py:exc', 'ISO8601SyntaxError'),
+    ('py:exc', 'StrftimeSyntaxError'),
 ]
 
 # List of patterns, relative to source directory, that match files and

src/reference/api/exceptions.rst

@@ -0,0 +1,8 @@
+Exceptions
+==========
+
+.. automodule:: cylc.flow.exceptions
+   :members:
+
+.. automodule:: cylc.flow.parsec.exceptions
+   :members:

src/reference/api/index.rst

@@ -3,6 +3,8 @@ Cylc API
 
 
 .. toctree::
+   :maxdepth: 2
 
    scan
    zmq
+   exceptions