docs: post-Sphinx (non-content) enhancements

[sadielbartholomew]

Master listing of all enhancements proposed for the documentation (formerly the User Guide & Suite Design Guides) under Sphinx infrastructure, after bare-bones conversion from LaTeX sourcing (#2910). Let's utilise the newly-obtained power of Sphinx! :muscle:

NB: do not use this to list proposed content improvements, only enhancements to the ultimate presentation output of the material e.g. to aspects of the infrastructure, new features, formatting, styling, bells & whistles, etc. Feel free to move items to separate issues, if appropriate, but please make annotations to that effect for tracking purposes.

• :eight_pointed_black_star: : should be addressed first, since it requires full-team input & determines what URLs will point to what content & we will want to establish stable URLs early on for support purposes etc;
• :large_orange_diamond: : see https://github.com/cylc/cylc/issues/2651#issuecomment-395437604, giving in marked cases further information not explicitly outlined here.

Constructional enhancements

• [x] (:eight_pointed_black_star:) Restructuring: change the sectioning hierarchy, as displayed with all levels included in the table of contents listing on the main index page. Notably:
  • the sub-sections under 'Appendices' should be relocated to named (sub-)sections, as relevant;
  • it is standard for software docs to have a 'Getting Started' top-level heading now, & we could move the installation & tutorial sections, for example, under this.
• ~Builds, possibly built using associated style files if it seems appropriate~ #16, #26
  • ~[x] to PDF;~
  • ~[x] to (HTML) slides, via the hieroglyph slide builder;~
  • ~[x] to ePub.~
• Relationship to the Rose documentation:
  • ~[x] move the Cylc tutorial from there to here;~ #18, 26
  • ~[x] make use of intersphinx to link seamlessly between the two documentation sets (see https://github.com/cylc/cylc/issues/2651#issuecomment-407809971).~ #38
  • [x] standardise the Rose and Cylc documentation for ease of maintenance
  • [x] ~copy across documentation versioning system from Rose~ #26
• [x] Deployment to the main cylc web site upon new release: automate further (see https://github.com/cylc/cylc/pull/2910#issuecomment-452978094)
• ~[ ] Replace build method: #2910 created for simplicity the command cylc make-docs, a minimal bash script, but integration into a setup.py would be superior (see https://github.com/cylc/cylc/pull/2910#issuecomment-453883088 & https://github.com/cylc/cylc/pull/2910#issuecomment-453884314)~ #20
• [x] ~Hosting: instead externally on 'Read the Docs' & point to this from previous access points? (see https://github.com/cylc/cylc/pull/2910#issuecomment-453962732 & second half of https://github.com/cylc/cylc/pull/2910#issuecomment-454760407)~ GH pages working well.

Auto-documentation (:large_orange_diamond: Auto Documentation section)

To generate:

• Interfaces, each to display in an intuitive format incorporating standard item components e.g. for the CLI the usage, arguments & options elements:
  • [ ] CLI (Cylc API) (currently documented, but only via primitive bash script);
  • [x] suite.rc reference i.e. the suite configuration API;
  • [ ] suite API (HTTP);
  • [x] python interfaces relevant to Cylc, e.g. modules such as Jinja2 filters.
• [x] The suite database. #2483
• [ ] Software dependencies.

Content formatting & styling (markup, directives, roles, etc.)

• [x] deprecation, versionadded & versionchanged directives: for items in config references.
• [x] seealso directive: for many instances of plain-text "see (also) sub-section XYZ" pointers to improve internal cross-referencing.
• [x] Highlights & pull-quotes: to emphasise key points.
• [x] Better use of admonitions: e.g. tip, hint, error, for specially-rendered topics. Only some notes & warnings directives have been added in for obvious cases as part of #2910.
• [x] Index of terms & objects: populate this by adding in index directives at appropriate places, as it is automatically included in the built docs, but currently left blank.
  • Blank indexes now removed.
  • Glossary page added.
  • Configs auto documented.
  • The need for dedicated indexes is not clear. Ticking off for now.
• [x] Sub-figures: for multiple images intended to be grouped as one figure. Currently consecutive standard figures, with the final captioned, are used.
  • Easier solution, removed complex figures!
• [ ] tree-command-like directory structures in remote-job-management.rst: these were written up manually, ~but there might be extensions~ (or better ways to write out explicitly) for improved display. (migrated to https://github.com/cylc/cylc-sphinx-extensions/issues/5)

Testing & quality-checking

• [ ] Test to ensure that the syntax highlighting doesn't encounter any erroneous syntax (https://github.com/cylc/cylc/issues/2651#issuecomment-451907024)
• [ ] ~Testing to ensure consistency between code snippets & graphs they are meant to map to, to prevent mismatches e.g. #2874 from updates~ use minicylc directive from Rose to generate graphs to ensure images are in sync with code snippets
• [ ] Validation of suite.rc code blocks

Visual elements

• [x] Dynamic embedded scheduling graphs: => issue migrated to https://github.com/cylc/cylc-sphinx-extensions/issues/4
  • add in the minicylc directive, as created for the Rose docs, for animated graphs;
  • build a (primitive) Cylc scheduler in Javascript (see https://github.com/cylc/cylc/issues/2651#issuecomment-441063157);
  • use cylc graphcommand to generate diagrams of example suites (see https://github.com/cylc/cylc/issues/2651#issuecomment-440649431) (see also the minicylc directive).
• [x] Further extensions to minicylc: => issue migrated to https://github.com/cylc/cylc-sphinx-extensions/issues/4)
  • Conditional expressions;
  • Cycling;
  • Suicide Triggers;
  • Parametrisation.

[sadielbartholomew]

@oliver-sanders I have tried to collate & organise all comments regarding follow-on work contained in Issue #2651 and PR #2910 into the above listing. However, you have provided most input to the former. In light of this could you please double check that all of your recordings there have been registered and linked here, as appropriate, given that I have closed the Issue in question? Feel free to edit the listing as you wish.

[kinow]

Edited to add link to #2483 next to the suite database text.

[oliver-sanders]

Edit: updated for #26, #38