consolidate rose & cylc sphinx extensions

[oliver-sanders]

Remove duplicate code by making one documentation system (presumably Rose) dependent on the other (Cylc?).

Example duplication, src/ext/cylc_lang,py Cylc language lexer.

[update]: see the sister PR https://github.com/metomi/rose/pull/2374/files

[kinow]

+1 for both removing duplicate, and also for adding dependency to cylc-flow from rose. I think it makes sense this direction, as Rose uses Cylc, but not the other way.

[oliver-sanders]

OK, done some quick thinking on this.

Sphinx extensions can have:

• A python part
  • currently in src/ext
• Static resources (css, js, etc)
  • currently in src/_static
• Software dependencies (e.g. graphviz)
  • currently installed into environment

Because the stuff is spread in different places and because the Rose docs are not a subset of the Cylc docs it's kinda hard to import Cylc Sphinx extensions from Rose.

Possible solution, put the sphinx extensions in yet another repository and then either:

• install them as dependencies in setup.py
• include the source as a git submodule

I guess one "super" repository to contain all of the extensions would suffice, no real need to break things down further from there.

It does mean yet another repository, yet another place to document issues but it would cut down on duplication.

@kinow thoughts?

[kinow]

I guess one "super" repository to contain all of the extensions would suffice, no real need to break things down further from there.

+1

It does mean yet another repository, yet another place to document issues but it would cut down on duplication.

Makes sense to me. In the end this extra repository would make our work easier by maintaining it in a single place.

And thanks for the explanation about the Sphinx part. Yesterday I tried to deploy our cylc-doc to a GitHub pages under my user account, and it failed to load the assets as they were under _static. GitHub pages reject directories (and I think files) that have underscores and dots. So I was wondering if that was a sphinx convention or if we defined that ourselves :) Now that's explained.

[oliver-sanders]

So the whole underscore thing comes from Jekyll which is the system GitHub uses to generate static sites for GH pages. TLDR stuff beginning with an underscore has special meaning in Jekyll.

The easiest solution is to maunually include these files in the Jekyll _config.yml file (e.g. in Rose).

PS: _static is a Sphinx convention, as is _build, _template etc. I think when I last looked at this you can rename some of these in the Sphinx conf.py but some are hardcoded in templates etc so it's best just to bodge Jekyll.

[kinow]

No worries. I think we will deploy it to Read The Docs? So it shouldn't be a problem I think?

[oliver-sanders]

OK, work started https://github.com/cylc/cylc-sphinx-extensions

[oliver-sanders]

Part 1: Copy extensions to new repository cylc/cylc-sphinx-extensions#2

Need volunteers to review, as it's a new repo I can't assign...

[kinow]

Need volunteers to review, as it's a new repo I can't assign...

You should be able to assign now (thanks to @hjoliver !)

[oliver-sanders]

Done in several earlier PRs.