Basic Metadata Writing extension

Author: wxtim

cylc/sphinx_ext/cylc_lang/__init__.py

@@ -15,7 +15,22 @@
 # 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,
+    CylcMetadataDirective
+)
+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
@@ -157,7 +172,9 @@
             cylc.flow.parsec.validate.ParsecValidator.V_TYPE_HELP
             cylc.flow.parsec.validate.CylcConfigValidator.V_TYPE_HELP
 
+'''
 
+rawdoc3 = '''
 Directives
 ----------
 
@@ -181,19 +198,59 @@
 
          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 = """
+.. rst:directive:: cylc-metadata
+
+   Get a Cylc Configuration and render metadata fields.
+
+   .. rst:directive:option:: source
+      :type: string
+
+      If set, renders the metadata of a workflow, otherwise the global
+      config.
+
+   .. rst:directive:option:: global
+      :type: string
+
+      Set CYLC_SITE_CONF_PATH to this value.
+
+      .. note::
+
+         If you have a user config this will still override the site
+         config!
+
+   ----
+
+   Workflow Config
+   ^^^^^^^^^^^^^^^
 
+   .. rst-example::
+
+      .. cylc-metadata::
+         :source: {workflow_path}
+
+   ----
+
+   Global Config
+   ^^^^^^^^^^^^^
+
+   .. rst-example::
+
+      .. cylc-metadata::
+         :global: {workflow_path}
+
+"""
+
+workflow_path = Path(__file__).parent.parent.parent.parent / 'etc'
+__doc__ = (
+    rawdoc1
+    + rawdoc2.format(workflow_path=workflow_path)
+    + rawdoc3
+)
 
 __all__ = [
     'CylcAutoDirective',
@@ -214,5 +271,6 @@ def setup(app):
     app.add_domain(ParsecDomain)
     app.add_directive('auto-cylc-conf', CylcAutoDirective)
     app.add_directive('auto-cylc-type', CylcAutoTypeDirective)
+    app.add_directive('cylc-metadata', CylcMetadataDirective)
     app.add_directive('cylc-scope', CylcScopeDirective)
     return {'version': __version__, 'parallel_read_safe': True}