Open sadielbartholomew opened 5 years ago
@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.
Edited to add link to #2483 next to the suite database text.
Edit: updated for #26, #38
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.
Constructional enhancements
cylc make-docs
, a minimal bash script, but integration into asetup.py
would be superior (see https://github.com/cylc/cylc/pull/2910#issuecomment-453883088 & https://github.com/cylc/cylc/pull/2910#issuecomment-453884314)~ #20Auto-documentation (:large_orange_diamond:
Auto Documentation
section)To generate:
suite.rc
reference i.e. the suite configuration API;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.tip
,hint
,error
, for specially-rendered topics. Only somenotes
&warnings
directives have been added in for obvious cases as part of #2910.tree
-command-like directory structures inremote-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
minicylc
directive from Rose to generate graphs to ensure images are in sync with code snippetssuite.rc
code blocksVisual elements
minicylc
directive, as created for the Rose docs, for animated graphs;cylc graph
command to generate diagrams of example suites (see https://github.com/cylc/cylc/issues/2651#issuecomment-440649431) (see also theminicylc
directive).minicylc
: => issue migrated to https://github.com/cylc/cylc-sphinx-extensions/issues/4)