excessive escape characters in doco

[ColemanTom]

I was looking for something in the doco and noticed, what I believe are a lot of unintentional \ characters. For example, in https://cylc.github.io/doc/built-sphinx-single/index.html#scheduling-xtriggers-many

Replace \_\_MANY\_\_ with any user-defined event trigger I assume is meant to be Replace __MANY__ with any user-defined event trigger? I just wanted to check just in case it is intended.

[kinow]

I think that's not intentional @ColemanTom. Would you like to send a pull request for that?

[ColemanTom]

Ok. Any idea how to fix

https://cylc.github.io/doc/built-sphinx-single/index.html#runtime-name-parameter-environment-templates

Specifically, the heading 15.1.5.1.17.1. [runtime] -> [[__NAME__]] -> [[[parameter environment templates]]] -> __VARIABLE__ not being displayed as a heading?

[ColemanTom]

Oh, maybe that is a heading, its just less pronounced so I didn't realise..

[kinow]

@ColemanTom

Oh, maybe that is a heading, its just less pronounced so I didn't realise..

Yeah, but what's weird, is that if you look at the source code, at least for me, that's an <h7>... I believe that is not part of the HTML standard tags. But I am not really good with Sphinx, maybe that's expected.

[ColemanTom]

A quick google suggests you are correct, h7 isn't a normal tag. I can't see any custom CSS applied to the tag. Perhaps some could be added if h7 is required?

[hjoliver]

Escaped underscores have slipped through from the original LaTeX source! (Good spotting).

[sadielbartholomew]

Escaped underscores have slipped through from the original LaTeX source! (Good spotting).

Yes, sorry all, just reading through this, it was simply the case as above; I remember when converting the docs from LaTeX I removed an awful lot of the escape characters but I clearly missed some. Well spotted @ColemanTom.

Looking into the headings aspect, you've actually noticed another bug of sorts: there are a large amount of headings not displaying properly (at least under the 15.1. Suite.rc Reference top-level section) in the single-page build, but somehow not in the multi-page build. For example, compare:

• Multi-page build, headings correct: https://cylc.github.io/doc/built-sphinx/appendices/suiterc-config-ref.html#runtime-name-meta
• Single-page build, lots of headings not recognised as such: https://cylc.github.io/doc/built-sphinx-single/index.html#runtime-name-meta

Though as pointed out, Sphinx must recognise them as headings to some extent because they have not messed up the numbering of ('sub-', etc.) headings at all (thankfully), since these are consistent in the multi- & single- page builds as linked above.

[sadielbartholomew]

in the single-page build, but somehow not in the multi-page build

Actually, thinking about this (after a lunch break), I suspect that it is simply that Sphinx only displays headings up to a certain level in the 'sub-' hierarchy, & because the single-page build combines all multi-page page headings under one page under a generic 'Cylc documentation' top-level title, each heading gets demoted one level relative to the multi-page build, e.g:

• Multi-page:
• Single-page:

Therefore we would just need to specify that another level of headings get displayed in a way that can be instantly recognised as a heading, notably being in the same colour as other headings. Sphinx will hopefully provide an easy way to configure this.

[oliver-sanders]

Closed by #121