Cylc Config Metadata Directive

.github/workflows/test.yml

@@ -20,7 +20,7 @@ jobs:
     timeout-minutes: 5
     strategy:
       matrix:
-        python-version: ['3.7', '3']
+        python-version: ['3.14', '3']
       fail-fast: false
     env:
         PYTEST_ADDOPTS: --color=yes

cylc/sphinx_ext/cylc_lang/__init__.py

@@ -15,7 +15,23 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 # -----------------------------------------------------------------------------
-'''An extension providing pygments lexers for the Cylc flow.cylc language.
+from pathlib import Path
+from cylc.sphinx_ext.cylc_lang.autodocumenters import (
+    CylcAutoDirective,
+    CylcAutoTypeDirective,
+    CylcWorkflowDirective,
+    CylcGlobalDirective,
+)
+from cylc.sphinx_ext.cylc_lang.domains import (
+    ParsecDomain,
+    CylcDomain,
+    CylcScopeDirective
+)
+from cylc.sphinx_ext.cylc_lang.lexers import CylcLexer, CylcGraphLexer
+
+
+rawdoc1 = '''An extension providing pygments lexers for the Cylc flow.cylc
+language.
 
 
 Pygments Lexers
@@ -165,7 +181,9 @@
             cylc.flow.parsec.validate.ParsecValidator.V_TYPE_HELP
             cylc.flow.parsec.validate.CylcConfigValidator.V_TYPE_HELP
 
+'''
 
+rawdoc3 = '''
 Directives
 ----------
 
@@ -189,20 +207,64 @@
 
          This resets it to the hardcoded default which is ``flow.cylc``.
 
+
+
 '''
 
-from cylc.sphinx_ext.cylc_lang.autodocumenters import (
-    CylcAutoDirective,
-    CylcAutoTypeDirective
-)
-from cylc.sphinx_ext.cylc_lang.domains import (
-    ParsecDomain,
-    CylcDomain,
-    CylcScopeDirective
-)
-from cylc.sphinx_ext.cylc_lang.lexers import CylcLexer, CylcGraphLexer
+rawdoc2 = """
+
+Cylc Global
+^^^^^^^^^^^
+
+.. rst:directive:: .. auto-global-cylc:: source
+
+   Get a Cylc Global Configuration and render metadata fields.
+
+   If the optional source argument is give,
+   set ``CYLC_SITE_CONF_PATH`` to this value.
+
+   .. note::
+
+      If you have a user config this will still override the site
+      config!
+
+   .. rst-example::
+
+      .. auto-cylc-global:: {workflow_path}
+         :show:
+            foo,
+            install target,
+            bar,
+            qax
 
 
+Cylc Workflow
+^^^^^^^^^^^^^
+
+.. rst:directive:: .. auto-cylc-workflow:: source
+
+   Get a Cylc Workflow Configuration from source and document the settings.
+
+   The task-items variable allows you to select runtime config items to
+   append to the metadata. For example you might want the platform or
+   environment section included in task metadata.
+
+   .. rst-example::
+
+      .. auto-cylc-workflow:: {workflow_path}/workflow
+         :task-items:
+            environment,
+            platform
+"""
+
+
+workflow_path = Path(__file__).parent.parent.parent.parent / 'etc'
+__doc__ = (
+    rawdoc1
+    + rawdoc2.format(workflow_path=workflow_path)
+    + rawdoc3
+)
+
 __all__ = [
     'CylcAutoDirective',
     'CylcDomain',
@@ -222,5 +284,7 @@ def setup(app):
     app.add_domain(ParsecDomain)
     app.add_directive('auto-cylc-conf', CylcAutoDirective)
     app.add_directive('auto-cylc-type', CylcAutoTypeDirective)
+    app.add_directive('auto-cylc-workflow', CylcWorkflowDirective)
+    app.add_directive('auto-cylc-global', CylcGlobalDirective)
     app.add_directive('cylc-scope', CylcScopeDirective)
     return {'version': __version__, 'parallel_read_safe': True}