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! 💪

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.

• ✴️ : 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;
• 🔶 : see User Guide: convert to sphinx cylc-flow#2651 (comment), giving in marked cases further information not explicitly outlined here.

Constructional enhancements

• (: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 remove output format constraint #16, documentation building #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; tutorial: transfer the Cylc tutorial from the Rose documentation #18, 26
  • [x] make use of intersphinx to link seamlessly between the two documentation sets (see User Guide: convert to sphinx cylc-flow#2651 (comment)). Cylc Tutorial #38
  • standardise the Rose and Cylc documentation for ease of maintenance
  • copy across documentation versioning system from Rose documentation building #26
• Deployment to the main cylc web site upon new release: automate further (see Docs (User + Design Guides) conversion to Sphinx cylc-flow#2910 (comment))
• [ ] 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 Docs (User + Design Guides) conversion to Sphinx cylc-flow#2910 (comment) & Docs (User + Design Guides) conversion to Sphinx cylc-flow#2910 (comment)) doc build and dependencies #20
• Hosting: instead externally on 'Read the Docs' & point to this from previous access points? (see Docs (User + Design Guides) conversion to Sphinx cylc-flow#2910 (comment) & second half of Docs (User + Design Guides) conversion to Sphinx cylc-flow#2910 (comment)) 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);
  • suite.rc reference i.e. the suite configuration API;
  • suite API (HTTP);
  • python interfaces relevant to Cylc, e.g. modules such as Jinja2 filters.
• The suite database. #2483
• Software dependencies.

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

• deprecation, versionadded & versionchanged directives: for items in config references.
• seealso directive: for many instances of plain-text "see (also) sub-section XYZ" pointers to improve internal cross-referencing.
• Highlights & pull-quotes: to emphasise key points.
• 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.
• 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.
• 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 tree: extension for displaying file hierarchies  cylc-sphinx-extensions#5)

Testing & quality-checking

• Test to ensure that the syntax highlighting doesn't encounter any erroneous syntax (User Guide: convert to sphinx cylc-flow#2651 (comment))
• 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

• Dynamic embedded scheduling graphs: => issue migrated to minicylc: improve capabilities cylc-sphinx-extensions#4
  • add in the minicylc directive, as created for the Rose docs, for animated graphs;
  • build a (primitive) Cylc scheduler in Javascript (see User Guide: convert to sphinx cylc-flow#2651 (comment));
  • use cylc graphcommand to generate diagrams of example suites (see User Guide: convert to sphinx cylc-flow#2651 (comment)) (see also the minicylc directive).
• Further extensions to minicylc: => issue migrated to minicylc: improve capabilities cylc-sphinx-extensions#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