cylc domain

.github/workflows/test.yml

@@ -21,6 +21,7 @@ jobs:
             node-version: '10.x'
       - name: install
         run: |
+          pip install git+https://github.com/cylc/cylc-flow/  # install latest cylc-flow
           pip install -e .[all]
           npm install -g eslint
           sudo apt-get install -y graphviz
@@ -33,4 +34,8 @@ jobs:
           pytest
       - name: build
         run: |
-          make html linkcheck
+          make html slides linkcheck
+      - name: debug
+        if: failure()
+        run: |
+          cat /tmp/sphinx-err*  # sphinx traceback

Makefile

@@ -1,7 +1,7 @@
 # Minimal makefile for Sphinx documentation
 
 # You can set these variables from the command line:
-SPHINXOPTS = -W
+SPHINXOPTS = -Wn
 SPHINXBUILD = sphinx-build
 SOURCEDIR = .
 BUILDDIR = _build
@@ -21,5 +21,4 @@ clean:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile cli
 	# build documentation
-	sphinx-autogen -i index.rst -o extensions
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.rst

@@ -28,7 +28,7 @@ Note the ``minicylc`` extension requires ``graphviz``::
 Usage
 -----
 
-To use an extension register it in your project's ``conf.py``::
+To use an extension register it in your project's ``conf.py`` e.g::
 
    extension = [
        'cylc.sphinx_ext.cylc_lang'
@@ -54,7 +54,7 @@ Extensions are auto-documented from their module docstrings.
 
 Build documentation by running::
 
-   $ make clean <format>  # e.g. make html
+   $ make clean <format>  # e.g. make html slides
 
 This documentation build serves as a simple test battery (warnings will cause
 it to fail), for everything else there's pytest::

_templates/mymodule.rst

@@ -0,0 +1,7 @@
+{#
+   template for minimal documentation of a module (i.e. docstring only)
+#}
+
+{{ fullname.split(".")[-1] | escape | underline}}
+
+.. automodule:: {{ fullname }}

conf.py

@@ -27,15 +27,18 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.graphviz',
+    'sphinx.ext.intersphinx',
 
     # cylc.sphinx_ext extensions
     'cylc.sphinx_ext.cylc_lang',
     'cylc.sphinx_ext.diff_selection',
     'cylc.sphinx_ext.grid_table',
-    'cylc.sphinx_ext.hieroglyph_theme_addons',
+    'cylc.sphinx_ext.hieroglyph_addons',
+    'cylc.sphinx_ext.hieroglyph_patch',
     'cylc.sphinx_ext.minicylc',
     'cylc.sphinx_ext.practical',
     'cylc.sphinx_ext.rtd_theme_addons',
+    'cylc.sphinx_ext.rst_example',
     'cylc.sphinx_ext.sub_lang',
 
     # addons required by extensions
@@ -45,3 +48,17 @@
 
 # minicylc settings
 graphviz_output_format = 'svg'
+graphviz_dot_args = ['-Gfontname=sans', '-Nfontname=sans', '-Gbgcolor=none']
+
+# autosummary options
+templates_path = ['_templates']
+autosummary_generate = True
+autosummary_imported_members = True
+
+# external references
+intersphinx_mapping = {
+    'sphinx': ('http://www.sphinx-doc.org/', None)
+}
+
+# avoid issues with transitive files
+exclude_patterns = ['_build', 'venv', 'env']

cylc/sphinx_ext/cylc_lang/__init__.py

@@ -17,11 +17,16 @@
 # -----------------------------------------------------------------------------
 '''An extension providing pygments lexers for the Cylc suite.rc language.
 
-.. rubric:: Examples
 
-Pygments language: `cylc`
+Pygments Lexers
+---------------
 
-.. code-block:: rst
+``cylc``
+^^^^^^^^
+
+Lexer for the Cylc ``.rc`` language and ``suite.rc`` extensions.
+
+.. rst-example::
 
    .. code-block:: cylc
 
@@ -34,37 +39,142 @@
                       (foo & bar) => pub
                   """
 
-.. code-block:: cylc
-
-   [scheduling]
-       initial cycle point = 2000
-       [[dependencies]]
-           [[[P1Y]]]
-               graph = """
-                   @wall_clock => foo => bar
-                   (foo & bar) => pub
-               """
+``cylc-graph``
+^^^^^^^^^^^^^^
 
-Pygments language: `cylc-graph`
+Lexer for the Cylc "graph string" language.
 
-.. code-block:: rst
+.. rst-example::
 
    .. code-block:: cylc-graph
 
       @wall_clock => foo => bar
       (foo & bar) => pub
 
-.. code-block:: cylc-graph
 
-   @wall_clock => foo => bar
-   (foo & bar) => pub
+Domains
+-------
+
+Sphinx domain for ``cylc`` configurations.
+
+``cylc``
+^^^^^^^^
+
+.. rst-example::
+
+   .. cylc:conf:: my-conf1.rc
+
+     .. cylc:setting:: foo
+
+        a setting called ``foo``.
+
+       see also :cylc:setting:`[bar]pub` (this is a relative reference)
+
+     .. cylc:section:: bar
+
+        a section called ``bar``.
+
+        .. cylc:setting:: pub
+
+           a setting called ``pub``
+
+           .. cylc:value:: integer
+
+              :deprecated: 1.2.3
+
+              seconds as an integer.
+
+              the newer :cylc:value:`string` is preferred (this is also
+              a relative reference).
+
+           .. cylc:value:: string
+
+              an iso8601 duration.
+
+Auto Documenters
+----------------
+
+.. rst:directive:: auto-cylc-conf
+
+   Directive for documenting Parsec specification dictionaries.
+
+   .. code-block:: rst
+
+      .. auto-cylc-conf:: name-of-conf python.namespace.SPEC
+
+   For development the ``SPEC`` can alternatively be provided in JSON
+   format in the directive body.
+
+   .. rst-example::
+
+      .. auto-cylc-conf:: my-conf2.rc
+
+         {
+             "foo": {
+                 "bar": {
+                     "pub": ["V_BOOLEAN", "True"]
+                 },
+                 "baz": ["V_BOOLEAN", "True", "True", "False"]
+             }
+         }
+
+      Expected usage would look like this:
+
+      .. code-block:: rst
+
+         .. auto-cylc-conf:: suite cylc.flow.cfgspec.suite.SPEC
+
+.. rst:directive:: auto-cylc-type
+
+   Directive for documenting Parsec types.
+
+   Extracts type information from ``cylc.flow``, or, for development purposes,
+   from JSON in the directive body.
+
+   .. rst-example::
+
+      .. auto-cylc-type::
+
+         [
+             {
+                 "name": "boolean",
+                 "help": "A boolean in Python format",
+                 "options": ["True", "False"],
+                 "examples": {
+                     "True": "/usr/bin/true to your heart",
+                     "False": "oh noes"
+                 },
+                 "references": [
+                     ["rst:dir", "auto-cylc-type"]
+                 ]
+             }
+         ]
+
+      Expected usage would look like this:
+
+      .. code-block:: rst
+
+         .. auto-cylc-type::
+            cylc.flow.parsec.validate.ParsecValidator.V_TYPE_HELP
+            cylc.flow.parsec.validate.CylcConfigValidator.V_TYPE_HELP
 
 '''
 
+from cylc.sphinx_ext.cylc_lang.autodocumenters import (
+    CylcAutoDirective,
+    CylcAutoTypeDirective
+)
+from cylc.sphinx_ext.cylc_lang.domains import CylcDomain
 from cylc.sphinx_ext.cylc_lang.lexers import CylcLexer, CylcGraphLexer
 
 
-__all__ = ['CylcLexer', 'CylcGraphLexer', 'setup']
+__all__ = [
+    'CylcAutoDirective',
+    'CylcDomain',
+    'CylcGraphLexer',
+    'CylcLexer',
+    'setup'
+]
 
 __version__ = '1.0.0'
 
@@ -73,4 +183,7 @@ def setup(app):
     """Sphinx plugin setup function."""
     app.add_lexer('cylc', CylcLexer())
     app.add_lexer('cylc-graph', CylcGraphLexer())
+    app.add_domain(CylcDomain)
+    app.add_directive('auto-cylc-conf', CylcAutoDirective)
+    app.add_directive('auto-cylc-type', CylcAutoTypeDirective)
     return {'version': __version__, 'parallel_read_safe': True}