Coder Social home page Coder Social logo

cylc / cylc-doc Goto Github PK

View Code? Open in Web Editor NEW
9.0 7.0 19.0 118.74 MB

Documentation (User Guide, Cheat Sheets, etc.) for the Cylc Workflow Engine.

Home Page: https://cylc.github.io/cylc-doc/

License: GNU General Public License v3.0

Shell 8.60% Python 79.27% Makefile 7.55% HTML 2.13% CSS 2.45%
cylc

cylc-doc's Introduction

PyPI Anaconda-Server Badge chat forum Documentation

Cylc (pronounced silk) is a general purpose workflow engine that also manages cycling systems very efficiently. It is used in production weather, climate, and environmental forecasting on HPC, but is not specialized to those domains.

Quick Start

Installation | Documentation

# install cylc
conda install cylc-flow

# extract an example to run
cylc get-resources examples/integer-cycling

# install and run it
cylc vip integer-cycling  # vip = validate, install and play

# watch it run
cylc tui integer-cycling

The Cylc Ecosystem

  • cylc-flow - The core Cylc Scheduler for defining and running workflows.
  • cylc-uiserver - The web-based Cylc graphical user interface for monitoring and controlling workflows.
  • cylc-rose - Provides integration with Rose.

Migrating From Cylc 7

Migration Guide | Migration Support

Cylc 8 can run most Cylc 7 workflows in compatibility mode with little to no changes, go through the migration guide for more details.

Quick summary of major changes:

  • Python 2 -> 3.
  • Internal communications converted from HTTPS to ZMQ (TCP).
  • PyGTK GUIs replaced by:
    • Terminal user interface (TUI) included in cylc-flow.
    • Web user interface provided by the cylc-uiserver package.
  • A new scheduling algorithm with support for branched workflows.
  • Command line changes:
    • cylc run <id> -> cylc play <id>
    • cylc restart <id> -> cylc play <id>
    • rose suite-run -> cylc install; cylc play <id>
  • The core package containing Cylc scheduler program has been renamed cylc-flow.
  • Cylc review has been removed, the Cylc 7 version remains Cylc 8 compatible.

Citations & Publications

DOI JOSS CISE

Copyright and Terms of Use

License

Copyright (C) 2008-2024 NIWA & British Crown (Met Office) & Contributors.

Cylc is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Cylc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Cylc. If not, see GNU licenses.

Contributing

Contributors Commit activity Last commit

Contributions welcome:

This repository contains some code that was generated by GitHub Copilot.

cylc-doc's People

Contributors

colemantom avatar damienfrancois avatar datamel avatar dependabot[bot] avatar douglowe avatar dpmatthews avatar dwsutherland avatar hjoliver avatar kinow avatar markgrahamdawson avatar matthewrmshin avatar metronnie avatar oliver-sanders avatar pletzer avatar sadielbartholomew avatar scottwales avatar swartn avatar tomektrzeciak avatar wxtim avatar yinjinglin avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar avatar avatar

Forkers

hjoliver oliver-sanders dwsutherland kinow sadielbartholomew wxtim datamel tomektrzeciak dpmatthews metronnie swartn damienfrancois douglowe pletzer yinjinglin colemantom scottwales markgrahamdawson

cylc-doc's Issues

Document how to manage task re-run by insertion

To re-run tasks that already ran, users need understand the following:

  • for a single task still in the task pool, just re-trigger it
  • for multiple inter-dependent tasks still in the task pool, manually reset them to waiting in upstream-first order
    • (in the other order they'll each just retrigger immediately, off of the old upstream task states)
    • (to stop the most-upstream one triggering immediately - if its prerequisites are already satisfied - reset its upstream dependants to failed then reset it to waiting; or just hold the suite).
  • tasks that have already disappeared from the task pool have to be re-inserted in order to re-run them
  • re-inserted tasks will trigger immediately if their dependencies can be satisfied by the current task pool
    • (unless the suite is held)

Also:

  • to re-insert and run tasks that were removed from the task pool by suicide triggers, you have to manipulate upstream state so that the suicide triggers are no longer satsified on insertion (else they'll just suicide again immediately) - cylc/cylc-flow#3282 (comment)

SDG: configuring job environments

Document use of site job-init-env.sh to configure platform environment for Cylc etc. (And custom job error handling script too, e.g. to dump the complete job environment to stderr).

Document how Cylc spawns new processes

Describe exactly what you would like to see in an upcoming release

Add documentation about processes spawning in Cylc 8.

Additional context

@oliver-sanders replied to a comment with an excellent explanation about some processes created in Cylc. I think that information is gold, and since we already have some backlog for documentation pre cylc-8 release, maybe we could include this task there too.

Ideally, I think we should document our intentions and what we expect to happen. Not sure if what we say will apply to all Python 3.x versions (e.g. Jython, IronPython, etc) nor to all *nix flavours (e.g. mac OS BSD variants, other BSD variants, etc). But that would still be useful to site admins and especially to developers.

Pull requests welcome!
This is an Open Source project - please consider contributing code yourself
(please read CONTRIBUTING.md before starting any work though).

docs/site: add "cheat sheet" overview(s) e.g. for CLI

Context

It is common to find "cheat sheets", condensed summaries in a single-tab-viewable or single-page-printable format, for aspects of many medium-to-large software projects, either included under the official documentation/website, or created & distributed independently by users. Some nice & fairly diverse examples are those, as linked, for Conda & pandas (official) & for Vuex & React (unofficial).

Cylc users could benefit from something similar. They may already have created their own, or primitive or non-prettified variants of, but to minimise dissemination of misinformation, deprecated content or unsuitable practices, we could maintain (an) official "cheat sheet(s)" under version control.

If we design a print out (version), we could hand it out at appropriate training or workshops, not just as a working aid but as a material resource to promote Cylc.

NB the Rose documentation has a Cheat Sheet page including standalone Cylc aspects which is very good, but minimal in scope, only covering a basic subset of the CLI for controlling & reviewing suites. We could create a more extensive complement under the Cylc project.

Considerations

Scope

We could sensibly condense a variety of content, but what would be worthwhile? Possibilities could be common aspects of:

  • CLI: especially day-to-day workflow commands. Awaiting the CLI revamp for Cylc 8 (#2972) though it could be easier &/or instructive to develop (the outline for) a CLI cheat sheet in tandem;
  • APIs that are exposed to users, namely configurations: suite & global (user) configuration file sections & items, & the Python interface for the former after #1962;
  • Syntax systems pivotal to such APIs: e.g. basic ISO8601 & Jinja2 constructs;
  • Terminology: key items from the (prospective) glossary populated into the index page (see https://github.com/cylc/cylc/issues/2933#issue-401726973), like those listed in the bare-bones current Terminology page;
  • Support: help channels & applicability of, as in the website support.html page.
  • Suite run directory structure: file & sub-directories, like a condensed version of an example tree command output in the docs tutorial.

Location & format

Should any cheat sheet(s) be included under (a page within) the built Sphinx documentation, as a resource under the Cylc repo for access via GitHub, or as a resource accessible from (e.g. linked from some, or its own, page under) the Cylc website?

In the former case, we are constrained to the reStructuredText format, otherwise we can use alternative markup languages or tools (see below) which might enable a more creative solution:

create in supply in
reStructuredText documentation, under built Sphinx page
web (HTML, CSS, perhaps a little JavaScript) separate root website page
LaTeX PDF form linked & downloadable from root website page
graphics software e.g. Inkscape image file e.g. PNG linked & downloadable from root website page

Capability for updating & reviewing content with change history rules out graphics software as a good choice, since updated images would need to be eyeballed for visual changes, lacking a traceable code diff (in the LaTeX case we could include the source code somewhere as well as the generated PDF).

Capabilities for customisation

Users have different levels of knowledge & work in different ways, so ideally we could create something that can be customised, to a sensible bare extent, to reflect that.

I envisage a one-page template into which boxes corresponding to select top-level items such as the examples listed under the above Scope section, with their own sub-categories as pluggable sub-boxes, can be dropped & dragged (to rearrange) as desired.

doc build and dependencies

#3 moved all docs here from the cylc-flow repository, simplistically taking the relevant bits of setup.py and cylc-check-software with it.

We need to decide how best to build the docs here, and how best to depend (where necessary) on other project/repo versions, particularly cylc-flow. (e.g. should we use setup.py here at all?)

See also #17

cylc user guide: more advanced cycling info

We could do with more information about advanced cycling features such as:

  • min(...)
  • truncation syntax (e.g. T-00 for start at the next 00 minutes)

and anything else that comes to mind.

Include, rather than write in, significant code examples

We should aim towards moving all significant chunks of hard-written code out of the .rst content files, & (if not located already in a known place, as in e.g. #65) into a separate dedicated directory as individual files, where they would be written into the built docs from the relevant file by the literalinclude: directive.

This would have various benefits, for example it would:

  • ensure that code snippets written out in the docs are up-to-date &/or consistent with codebase code they are referring to (as in e.g. #65);
  • allow us to validate such code for correctness, & against deprecation, certain blocks, notably suite.rc examples;
  • enable us to keep track of the number of code examples, & in turn to reference the figure accurately on the Cylc website as a major asset of the docs, & generally as a positive indicator for quality of project.

remove output format constraint

Allow the docs to be built in any of the formats supported by Sphinx.

If someone wants ePub let them build it.

This is completely trivial, just pass the name of the format through to Sphinx, default to HTML if no format provided. See how it is done in Rose.

Put all build-generated artefacts on built

I noticed that when I run make html singlehtml, the documentation appears to be generated under build/sphinx directory, but it looks like it also creates some directories under the doc.

If we run python setup.py bdist, then the bdist distribution package would go under build/bdist.linux-x86_64 or so. Since we have the sphinx folder being created under build, and setuptools is using that directory as well, then maybe we could stop using doc too?

Or is there a reason for the need of another folder for building the documentation?

Post-packaging update to installation instructions

The 'Installation' documentation section (quick link here) will need updating to reflect the state of Cylc 8, which has diverged greatly to Cylc 7 with respect to installation approaches & requirements.

The update should at least update the now-outdated information on:

  • revised requirements for other packages: Python 3.X range, further package dependencies, bundled packages (if any);
  • new installation method via PyPI (& conda, if possible at the time of closing) & setup.py;
  • new information required so users can understand how to inter-connect various Cylc 8 components, now in separate repositories.

xtriggers: undocumented restricted nature of results dict

The keys in the results dictionary returned in the satisfied signature (True, results) from a external trigger function become appended to the xtrigger name to form an environment variable identifier, which places many restrictions on these keys that are undocumented under the 'Custom Trigger Functions' section (only perhaps alluded to in the section 'Built-in Suite State Triggers' docs section which is referenced there). All that is stated there now is that "results is an arbitrary dictionary of information to be passed to dependent tasks"

If keys that do not conform are used, then all tasks depending on the xtrigger will fail, due to an error in exporting the variables named from the keys that get passed along. The job.err for the downstream tasks will show, e.g. if a key -2 was used:

... 01/job: line 34: export: `breakable_xtrigger_-2': not a valid identifier
2019-07-23T21:53:21+01:00 CRITICAL - failed/EXIT

Furthermore, there is no explicit mention that the results dict cannot be nested, to form some more complex data structure to pass through, which users could assume (I did so myself). Given the above, & after investigation, it does seem that results must be flat, else some very strange suite behaviour followed by suite shutdown (see cylc/cylc-flow#3237) results, so this should also be explicitly documented.

So, in short, the following should be clearly documented, under the 'Custom Trigger Functions' &/or 'Current Limitations' sections, ideally with an indication of the symptoms of invalid keys to help users debug::

  • results dict keys must be only contain characters that are valid within an environment variable (no easy standard to find but this thread suggests being all alphanumeric or underscores only as tested below);
  • the results dict must be flat.

Illustrative examples:

Use this custom trigger function in a basic suite & change the toggle variable systematically to observe the final task state of some trivial dependent tasks for each results case, where the dict value indicates whether the above problem emerges or not:

def breakable_script(toggle):
    if toggle == "singlequote":
        return (True, {'AMIBROKEN': 'no'})
    elif toggle == "underscore":
        return (True, {"Am_I_broken": "no"})
    elif toggle == "plainnumeric":
        return (True, {2: "no"})
    elif toggle == "space":
        return (True, {"Am I broken": "yes"})  # triggered tasks fail
    elif toggle == "dash":
        return (True, {"Am-I-broken": "yes"})  # triggered tasks fail
    elif toggle == "signednumeric":
        return (True, {-2: "yes"})  # broken: triggered tasks fail
    elif toggle == "comma":
        return (True, {"Am,I,broken": "yes"})  # triggered tasks fail
    elif toggle == "dot":
        return (True, {"Am.I.broken": "yes"})  # triggered tasks fail
    elif toggle == "float":
        return (True, {2.5: "yes"})  # broken: triggered tasks fail
    elif toggle == "slash":
        return (True, {"Am/I/broken": "yes"})  # triggered tasks fail
    elif toggle == "nested":
        res = {"dictA": {"keyA": "valueA"},
               "dictB": {"keyB": "valueB"}}
        return (True, res)  # this one is broken in a much funkier way!
    else:
        return True, {}

Demote forecasting context from very first UG section

Currently the User Guide opens with two items, 'Scheduling Forecast Suites' & 'EcoConnect', which chronicle in detailed paragraphs the NWP origins & background to Cylc.

While those sections are useful, having them as the very first sections could put off potential users who are considering Cylc for other contexts. It would be more appropriate to instead have the leading content concisely & directly summarise what Cylc is, or how to (install &) get started using it, as those are the most likely questions users will have when they consult the documentation.

Document how to skip suite-state polling

Users of suite-state polling for inter-suite triggering often hit the problem that polling tasks time out and fail if their suite is running a bit behind the clock and the upstream suite has been cold-started from scratch recently, thus wiping out its prior history of task completion.

Suite-state polling is typically used as a proxy for waiting on a file generated by a task in the upstream suite. If we checked for the file's existence and only bother to start polling the upstream generating task if it doesn't exist yet, this would largely eliminate the above problem. (And the downstream suite presumably has to know where the file lives anyway, in order to retrieve or use it).

So, to be documented:

  • Use a custom polling task (rather than the graph syntax short-cut) that checks for the existence of the target file and only calls cylc suite-state if necessary.
  • Or use a clock-expiring polling task, that only executes (and polls) if not too far behind the clock. However, this requires a more complex graph, with suicide triggers to remove expired tasks.

Finally, I considered adding a new option to cylc suite-state to call a user-supplied conditional check (e.g. file exists) before polling or not. But I don't think there's much point when you can just use a custom polling task, and further:

  • the new built-in external trigger mechanism cylc/cylc-flow#2423 will solve this problem - a suite-state polling trigger function can easily be written with a skip condition based on file existence or whatever

Update Suite Design Guide update for xtriggers

I was wondering if the Suite Design Guide could be updated with some details about xtriggers. I cannot see them mentioned anywhere in there, and I would personally find it useful to adopt a standard approach to using them from the outset. I don't know what to suggest as I have not used them yet. Or are they still too fresh to include in the design guide?

documentation versioning

We should make the documentation available for multiple versions of Cylc and adopt a build directory structure similar to Rose.

Now that we have split Cylc into multiple decoupled components this is a little awkward but I would suggest the Cylc Flow version is the one which matters for the documentation.

Versioning documentation is pretty simple, change the directory structure so that documentation is built under a version directory, in Rose we have:

sphinx/
    # the documentation source files
    conf.py
    index.rst
    ...
doc/
    # the built documentation
    formats.json  # file listing versions and formats for the theme to present as options.
    2019.01.0/
        html/
            index.html
            ...
        slides/
            index.html
            ...
        pdf/
            index.html
            tutorial.pdf
            ...
    2018.06.0/
         ...

Add troubleshooting to documentation

Being the one with less experience on troubleshooting Cylc, it has always been challenging when a cylc workflow did not behave the way I expected it to.

Other tools include sections with tips for admins and developers to troubleshoot the tools. Maybe we could do the same? Here are some cases that could be documented (feel free to edit this or add more comments):

  • troubleshoot problems building the project with pip, virtualenv, conda, etc. e.g. if you have a build directory from a previous python setup.py bdist it may interfere when using virtual environments

Updates to Jinja2 CUG documentation

We should document that our built-in pad filter is not needed. Just use Python-style string formatting:

foo_{{ "%05d" | format('3') }}

prints:

foo_00003

Clarfiy Python version range required for custom xtriggers

We currently do not specify any information about the necessary Python version that custom xtrigger functions can be written in, just that e.g. "Trigger functions are just normal Python functions".

From a quick test, in 8.0a0, an xtrigger written with Python 3 print function syntax works as it should, but if instead changed to Python 2 print statements, it throws a SyntaxError: Missing parentheses in call to 'print'.

From this & then going on to check in the cylc-flow codebase, it seems that xtriggers must more specifically be compatible with the version of Python required by cylc-flow, namely >=3.7.

A few questions, perhaps for @hjoliver or @kinow (but if anyone else wants to respond that is fine), before I add in this information:

  • Can you confirm, to double check, that the Python versions xtriggers must be written in to work properly is the same as the range of Python versions for cylc-flow?
  • For the docs, do we feel it is necessary to detail the minor version, or is it sufficient to state that xtriggers must be written in Python 3? I ask since xtriggers are usually quite simple, so it may be overkill to provide a more precise range?

polling intervals (and documentation of)

Undocumented features of task job polling:

  • there is a default "execution polling interval" of PT15M, even when polling is not configured
  • "execution timeout polling intervals" repeat ad infinitum until the job polls as finished. So 6*PT5M has exactly the same effect as PT5M

@matthewrmshin - can you a) confirm this behaviour; and b) confirm that it is intentional? (If so, we just need to document it)

Also, the logged health-check info seems to be misleading or meaningless in light of the above behaviour. E.g. for execution time limit = PT10S and execution timeout polling intervals = 6*PT5S:

...INFO - [foo.1] -health check settings: execution timeout=PT40S, polling intervals=PT15S,5*PT5S,...

where PT40S is PT10S plus 6*PT5S. Misleading because the "execution timeout is really still PT10S (e.g. as translated to PBS wall time directive) and in any case (as explained above) polling will not actually stop at PT40S - it will keep on polling until the job polls as finished. So what does this PT40S represent exactly? (Or do we actually set the timeout event to go off at PT40S in this case?)

Document "when the task pool matters".

(Ref recent discussion with Alan on Riot.im)

Users (unfortunately) need to understand the server "task pool" and how it evolves, in certain situations:

  • consequences of spawn-on-submit:

    • (implicit dependence foo[-P1]:submit => foo)
    • successive instances of a task can run concurrently, but not out of order
    • suites can stall due to un-spawned successors of tasks waiting downstream of a failed task (the next instance of the failed task itself will be spawned)

  • dynamic manipulation of workflow structure:

    • task-targeting commands and suicide triggers operate on task proxies currently present in the pool, not on the abstract workflow graph.

Spawn-on-demand (Cylc 9?) should fix these deficiencies. In the meantime, spawn to max active cycle points may be a good workaround for many suites.

Cylc Tutorial Suite

Follow-on from #38.

Find a new home for the Cylc Tutorial suite.

There are some issues to be migrated to wherever the Cylc Tutorial lands:

The Cylc Tutorial makes use of the rose tutorial command which is basically just a glorified rsync which copies resources from $ROSE_HOME/etc/tutorial to $HOME/cylc-run for the user to work on.

The tutorial suite contains:

  • Pillow dependency
  • Suites / code fragments
  • Bash script for extracting suites / code fragments

We will need to replace the rose tutorial command. The question is where to put it. Options:

  • Cylc Flow
    • + Tutorial suite always available with Cylc (Pillow ependency would go in extra_requires)
    • - Changes to the documentation and tutorial suite happen in different places
  • Cylc Doc
    • + Changes to the suite and documentation happen in the same place
    • - Extra repo to install creating a barrier for users
    • - Doesn't really make sense to distribute the suite and bash script with the built HTML
    • - Pretty-much all users will just use the online documentation anyway
  • Cylc Tutorial (new repo)
    • - Extra repo to install creating a barrier for users
    • - Changes to the documentation and tutorial suite happen in different places
    • - Too many repos dammit!

drop numbered sections

Numbered sections, the norm in scientific publication due to the PDF format, not quite at home in the world of technical documentation in HTML format.

sphinx doc search limitations

Unfortunately the sphinx doc "search engine" is very basic: it only searches individually indexed words, there's no way to search for patterns or phrases. This means searching for any multi-word phrase that has one or more common words in it will result in loads of spurious results.

[UPDATE: what's addressed so far on this issue]

  • Sphinx doc search is only for individual words - need phrase and regex search
  • Search result summaries show a bunch of nonsense text
  • Restore single-page User Guide document as an interim measure, for browser Ctrl-F search.

docs: post-Sphinx (non-content) enhancements

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 cylc/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 #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 cylc/cylc-flow#2651 (comment)). #38
    • standardise the Rose and Cylc documentation for ease of maintenance
    • copy across documentation versioning system from Rose #26
  • Deployment to the main cylc web site upon new release: automate further (see cylc/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 cylc/cylc-flow#2910 (comment) & cylc/cylc-flow#2910 (comment)) #20
  • Hosting: instead externally on 'Read the Docs' & point to this from previous access points? (see cylc/cylc-flow#2910 (comment) & second half of cylc/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 cylc/cylc-sphinx-extensions#5)

Testing & quality-checking

  • Test to ensure that the syntax highlighting doesn't encounter any erroneous syntax (cylc/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

More diagrams (to summarise or replace text content)

Perhaps stating the obvious, diagrams are much clearer & intuitive for explaining certain concepts than chunks of text, & they are also great for summarising content. #29 is a lovely example.

There are a lot of great schematics in the docs already, but the diagram to text ratio is still too low for my liking, & there are certain topics I read through & feel are crying out for a summarising, or substitute, diagram.

Bonus points if diagrams can be practicably auto-generated for content that can be & that is likely to change frequently, or at least is editable on an element-level so that PRs would not need to replace a whole image, where changes would be unclear.

revive old cylc tutorial

See "old tutorial" comment in #38

The old (and now removed) cylc tutorial wan't actually much of a tutorial but more, the beginnings of a user guide.

Recover any useful sections from the old tutorial and put them somewhere sensible.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.