initalise repository with sphinx extensions

[oliver-sanders]

Migrate Sphinx extensions here from the cylc/cylc-doc and metomi/rose projects.

• Theme extensions (css/js stored under _static) converted to Sphinx extensions.
  • Read The Docs theme modifications have been extracted into their own package for ease of portability.
  • Hieroglyph theme modifications have been extracted into their own package for ease of portability.
• Each extension is now a Python package.
  • The static resources (css/js) are now contained in this package.
  • These resources are registered with Sphinx via an absolute path.
• Extensions packaged under cylc.sphinx_ext.
• Auto-document extensions from their docstrings.
• Migrate tests.

The extension code has been reviewed in previous PRs, each extension is now documented with examples.

This repository is self documenting (run make html), the docs generated include explanations of each extension and example usage.

Where to put the built documentation i'm not so sure, gh-pages would be the obvious choice but I'm not sure how that would work with our Cylc organisation setup. Will push this to #1

[oliver-sanders]

metomi/rose#2374 is a reference for usage.

[kinow]

Few typos, but no blockers.

Tried running make clean, and make help, and both worked fine. Then tried running some of the commands listed in make help output (after installing via pip install -e .). But the commands I tried failed with

(venv) kinow@kinow-VirtualBox:~/Development/python/workspace/cylc-sphinx-extensions$ make html
# build documentation
sphinx-autogen -i index.rst -o extensions
[autosummary] generating autosummary for: index.rst
[autosummary] writing to extensions
Running Sphinx v2.1.2

Extension error:
Could not import extension hieroglyph (exception: No module named 'hieroglyph')
Makefile:23: recipe for target 'html' failed
make: *** [html] Error 2

So installed again with pip install -e .[all]. But make html now failed with:

(venv) kinow@kinow-VirtualBox:~/Development/python/workspace/cylc-sphinx-extensions$ make html
# build documentation
sphinx-autogen -i index.rst -o extensions
[autosummary] generating autosummary for: index.rst
[autosummary] writing to extensions
Running Sphinx v2.1.2
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 25 source files that are out of date
updating environment: 25 added, 0 changed, 0 removed
reading sources... [100%] venv/lib/python3.7/site-packages/sphinx/templates/apidoc/toc                                                                                                                             

Warning, treated as error:
/home/kinow/Development/python/workspace/cylc-sphinx-extensions/venv/lib/python3.7/site-packages/sphinx/ext/autosummary/templates/autosummary/base.rst:3:Error in "currentmodule" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. currentmodule:: {{ module }}
Makefile:23: recipe for target 'html' failed
make: *** [html] Error 2

But I think that may be OK as I haven't configured anything, and this is a repository for extensions, and not for the final documentation? I assume once we use it in a project with the right configuration, it will pass with no issues?

This PR is not breaking anything, so +1. Andthis is the first PR moving the old code here, so I think we canresolve the typos too if you prefer to fix them in another PR 👍

[oliver-sanders]

Then tried running some of the commands listed in make help output (after installing via pip install -e .). But the commands I tried failed

I've packaged dependencies a little strangely so that you don't have to install dependencies for all extensions to install some of the extensions. pip install -e . just installs the base dependencies.

To install dependencies for a specific extension do:

$ pip install -e [extension_name, ...]

To install everything:

$ pip install -e .[all]

[oliver-sanders]

@kinow Sorry for not copying the fixes from cylc-doc.

[kinow]

I've packaged dependencies a little strangely so that you don't have to install dependencies for all extensions to install some of the extensions. pip install -e . just installs the base dependencies.

It was me being slow to read the README and check setup.py 👍 looking good, and with namespace and all.

[oliver-sanders]

@wxtim volunteering you for you packaging experience. The code itself is old (moved from rose) so doesn't require much attention, the packaging, docs, setup etc is new and needs review.

[wxtim]

@wxtim volunteering you for you packaging experience. The code itself is old (moved from rose) so doesn't require much attention, the packaging, docs, setup etc is new and needs review.

Seen - Now looking

[wxtim]

Fancy adding a license?

[oliver-sanders]

Fancy adding a license?

Licence now on master, referenced in setup.py in this branch.

[wxtim]

👍