initalise repository with sphinx extensions

.eslintrc.json

@@ -0,0 +1,11 @@
+{
+    "extends": "eslint:recommended",
+    "parserOptions": {
+        "ecmaVersion": 6
+    },
+    "env": {
+        "browser": true,
+        "es6": true,
+        "jquery": true
+    }
+}

.travis.yml

@@ -0,0 +1,19 @@
+# Configuration for building documentation on Travis CI
+# See https://travis-ci.org/ for more info.
+
+---
+language: python
+dist: xenial
+python:
+    - '3.7'
+
+install:
+    - pip install -e .[all]
+    - npm install -g eslint
+    - sudo apt-get install -y graphviz
+
+script:
+    - pytest
+    - pycodestyle .
+    - eslint cylc/
+    - make html linkcheck

Makefile

@@ -0,0 +1,25 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line:
+SPHINXOPTS = -W
+SPHINXBUILD = sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -r extensions/ || true
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+.PHONY: help clean cli Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "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

@@ -1,8 +1,87 @@
 Cylc Sphinx Extensions
 ======================
 
-**Work In Progress**
+A library of extensions for documenting Cylc projects.
 
-A common repository of Sphinx extensions for documenting Cylc projects.
 
-See: https://github.com/cylc/cylc-doc/issues/39
+Installation
+------------
+
+Install all extensions (but not dependencies):
+
+.. code-block:: console
+
+   $ pip install git+https://github.com/cylc/cylc-sphinx-extensions.git
+
+OR all extensions + dependencies for specified extension(s) by name:
+
+.. code-block:: console
+
+   # TODO
+   $ pip install git+https://github.com/cylc/cylc-sphinx-extensions.git[cylc_lang]
+
+OR all extensions + dependencies for all extensions:
+
+.. code-block:: console
+
+   # TODO
+   $ pip install git+https://github.com/cylc/cylc-sphinx-extensions.git[all]
+
+Note the ``minicylc`` extension requires ``graphviz``:
+
+.. code-block:: console
+
+   # install graphviz from your package manager e.g:
+   $ sudo apt-get install -y graphviz
+
+
+Usage
+-----
+
+To use an extension register it in your project's ``conf.py``:
+
+.. code-block:: python
+
+   extension = [
+       'cylc.sphinx_ext.cylc_lang'
+   ]
+
+Some of these extensions are "auto-loading" and do not require any extra steps
+to activate.
+
+If the ``html_static_path`` configuration is set in your ``conf.py`` you will
+need to move this into a ``setup`` function, otherwise extensions cannot append
+to this path to add their own static resources e.g:
+
+.. code-block:: python
+
+   def setup(app):
+       app.config.html_static_path.append('_static')
+
+
+Development
+-----------
+
+Fork and clone ``https://github.com/cylc/cylc-sphinx-extensions.git``.
+
+Extensions are auto-documented from their module docstrings.
+
+Build documentation by running:
+
+.. code-block:: sub
+
+   $ make clean <format>  # e.g. make html
+
+This documentation build serves as a simple test battery (warnings will cause
+it to fail), for everything else there's pytest:
+
+.. code-block:: console
+
+   $ pytest
+
+For code linting:
+
+.. code-block:: console
+
+   $ pycodestyle .  # python
+   $ eslint cylc/   # javascript

conf.py

@@ -0,0 +1,47 @@
+# -----------------------------------------------------------------------------
+# THIS FILE IS PART OF THE CYLC SUITE ENGINE.
+# Copyright (C) 2008-2019 NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------
+from cylc.sphinx_ext import __version__
+
+# project settings
+master_doc = 'index'
+project = 'Cylc Sphinx Extensions'
+release = __version__
+html_theme = 'sphinx_rtd_theme'
+extensions = [
+    # sphinx built-in extensions
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.graphviz',
+
+    # 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.minicylc',
+    'cylc.sphinx_ext.practical',
+    'cylc.sphinx_ext.rtd_theme_addons',
+    'cylc.sphinx_ext.sub_lang',
+
+    # addons required by extensions
+    'hieroglyph',
+    'sphinx_rtd_theme',
+]
+
+# minicylc settings
+graphviz_output_format = 'svg'

cylc/sphinx_ext/__init__.py

@@ -0,0 +1,46 @@
+# -----------------------------------------------------------------------------
+# THIS FILE IS PART OF THE CYLC SUITE ENGINE.
+# Copyright (C) 2008-2019 NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# -----------------------------------------------------------------------------
+"""Sphinx extensions for documenting Cylc projects."""
+
+
+from pathlib import Path
+import os
+
+
+__version__ = '1.0.0'
+
+
+def register_static(app, extension):
+    """Register the _static directory of an extension.
+
+    Args:
+        app (Sphinx.App):
+            The sphinx application (as provided in the first argument of
+            the Sphinx ``setup()`` function.
+        extension (str):
+            The name of the Sphinx extension i.e. ``__name__``.
+
+    """
+    app.config.html_static_path.append(
+        str(
+            Path(__file__).resolve().parent.joinpath(
+                extension.replace(__name__ + '.', '').replace('.', os.sep),
+                '_static'
+            )
+        )
+    )

cylc/sphinx_ext/cylc_lang/__init__.py

@@ -0,0 +1,76 @@
+# -----------------------------------------------------------------------------
+# THIS FILE IS PART OF THE CYLC SUITE ENGINE.
+# Copyright (C) 2008-2019 NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# 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 suite.rc language.
+
+.. rubric:: Examples
+
+Pygments language: `cylc`
+
+.. code-block:: rst
+
+   .. code-block:: cylc
+
+      [scheduling]
+          initial cycle point = 2000
+          [[dependencies]]
+              [[[P1Y]]]
+                  graph = """
+                      @wall_clock => foo => bar
+                      (foo & bar) => pub
+                  """
+
+.. code-block:: cylc
+
+   [scheduling]
+       initial cycle point = 2000
+       [[dependencies]]
+           [[[P1Y]]]
+               graph = """
+                   @wall_clock => foo => bar
+                   (foo & bar) => pub
+               """
+
+Pygments language: `cylc-graph`
+
+.. code-block:: rst
+
+   .. code-block:: cylc-graph
+
+      @wall_clock => foo => bar
+      (foo & bar) => pub
+
+.. code-block:: cylc-graph
+
+   @wall_clock => foo => bar
+   (foo & bar) => pub
+
+'''
+
+from cylc.sphinx_ext.cylc_lang.lexers import CylcLexer, CylcGraphLexer
+
+
+__all__ = ['CylcLexer', 'CylcGraphLexer', 'setup']
+
+__version__ = '1.0.0'
+
+
+def setup(app):
+    """Sphinx plugin setup function."""
+    app.add_lexer('cylc', CylcLexer())
+    app.add_lexer('cylc-graph', CylcGraphLexer())
+    return {'version': __version__, 'parallel_read_safe': True}