Data

Tools

Indexes

Applications

Experiments

Open Source Science

https://github.com/cylc/cylc-doc

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

https://github.com/cylc/cylc-doc

Science Score: 26.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ○
    Committers with academic emails
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (11.7%) to scientific vocabulary

Keywords

cylc

Keywords from Contributors

scheduler workflow-management cycling-workflows job-scheduler metascheduler workflow-automation workflow-engine cylc-plugin rose archival
Last synced: 9 months ago · JSON representation

Repository

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

Basic Info
Statistics
  • Stars: 10
  • Watchers: 7
  • Forks: 21
  • Open Issues: 103
  • Releases: 0
Topics
cylc
Created about 7 years ago · Last pushed 9 months ago
Metadata Files
Readme Contributing License

README.md

Cylc Documentation

stable latest

Documentation for the Cylc Workflow Engine and its software ecosystem.

Writing

The documentation is written in ReStructuredText, for more information see:

  • https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
  • https://docutils.sourceforge.io/docs/user/rst/quickstart.html

We use the following convention for underlining headings:

```rest

Heading

Sub Heading

Sub Sub Heading ^^^^^^^^^^^^^^^ ```

ReStructuredText uses "natural indentation" where subsequent lines should follow the indentation of previous lines e.g:

```rest

Bullet Points

Indent subsequent lines two spaces:

  • Foo bar baz.
  • Pub.

Numbered Lists

Indent subsequent lines three spaces:

  1. Foo bar baz.
  2. Pub.

Directives

Indent subsequent lines three spaces:

.. directive:: argument

content

Note there should be one blank line before the content. ```

Hyperlinks that are likely to be common between pages can be put in src/hyperlinks.rst.include where they are available to all pages.

Cylc configurations should be referenced using :cylc:conf::

rest Tell Cylc what to run using :cylc:conf:`[runtime][<namespace>]script`.

Content from other Sphinx documented projects (Rose, Python, etc) can be linked to via intersphinx.

We use a few custom Sphinx extensions, for details see cylc-sphinx-extensions.

Label Guidance

Some things to bear in mind when defining labels in cylc-doc e.g. .. _my-label:

Namespace your labels

  • E.g. user-guide.something rather than something.
  • (Look for existing naming patterns before defining a new one).

Labels are imported from other projects (e.g. Rose, Jupyter Server, etc) * So avoid excessively vague labels where possible. * And only add labels where they are needed (labels are only for references, they don't serve any other purpose so adding excess ones doesn't benefit other things).

References resolve attach headers * So if a section has the heading Running Schedulers, then a good label might be user-guide.running-schedulers rather than scheduler runtime as this gives the person using the label a better idea of how it is likely to be presented.

Labels are forever * Other projects (e.g. metomi-docs) might use these labels!

Development

test nightly

Installation

Non Python Dependencies

There are two non-Python dependencies which must be installed:

  • graphviz
  • enchant

E.G. with Conda/Mamba:

console $ mamba install -c conda-forge graphviz enchant

Checkout & Install

console $ git clone git@github.com:cylc/cylc-doc.git cylc-doc $ cd cylc-doc $ pip install -e .

Simple Build

Build the docs using make:

console $ make html

The documentation builds incrementally, if you make changes to the Cylc source files run make clean:

console $ make clean html

Automatic Build

You can also get Sphinx to rebuild automatically when documentation files are modified. First install the optional dependency watch:

```console $ pip install -e .[watch]

```

Then build the watch target:

console $ make watch # you do not need to `make clean` with the `watch` target

This will monitor for changes in the cylc-doc repository and rebuild the documentation incrementally.

To also monitor for changes in the cylc-flow, cylc-uiserver and cylc-rose repositories use the watch-cylc target:

console $ make watch-cylc # you do not need to `make clean` with the `watch` target

This forces a complete rebuild every time a file is changed which is slow, but allows it to pick up changes to autodocumented items in the source code.

Note: Your Cylc repositories must be installed in editible mode i.e. pip install -e <repo> for this to work. Note: This might not work for all filesystems.

Testing

```console

note: -W tells Sphinx to fail on warnings

$ make html linkcheck SPHINXOPTS='-W' ```

Deploying

To document a new version of Cylc:

  • Create a tag with a name matching a released cylc-flow tag. git tag <tag> <commit> e.g. git tag 8.1.2 HEAD.
  • Push it to cylc/cylc-doc. git push upstream refs/tags/<tag>
  • Trigger the deploy workflow against that tag.

To update documentation for an existing version (post release):

  • Update the existing tag. git tag -d <tag>; git tag <tag> <commit>
  • Push it to cylc/cylc-doc. git push upstream refs/tags/<tag> -f
  • Trigger the deploy workflow against that tag.

To remove old documentation:

  • Trigger the undeploy workflow against the relevant tag.

To do any other weird or wonderful things:

  • Checkout upstream/gh-pages.
  • Make your changes and add them to a new commit.
  • Push to upstream/gh-pages (don't force push for ease of rollback).

Note: All changes made to the gh-pages branch are non-destructive (i.e. no force pushing) so all changes can be undone.

The deploy and undeploy actions are automations for convenience, however, everything can still be done by hand.

Warning: When you remove an old version from the documentation the old version is still in the commit history. After a while we may wish to rebase-squeeze the gh-pages branch to reduce the size of the repo.

This has not been automated on-purpose, though if it becomes a problem we could potentially setup a chron job to squash all but the last N commits.

Nightly Builds

The nightly action builds cylc-doc:master against cylc-flow:master and pushes the result up to upstream/gh-pages.

This action deletes its previous commits so the nightly build history is not preserved and does not require housekeeping.

Copyright and Terms of Use

License

Copyright (C) 2008-2025 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.

Owner

  • Name: The Cylc Workflow Engine
  • Login: cylc
  • Kind: organization
  • Email: hilary.oliver@niwa.co.nz
  • Location: Wellington, New Zealand

A workflow engine for cycling systems.

GitHub Events

Total
  • Issues event: 23
  • Delete event: 17
  • Issue comment event: 86
  • Push event: 487
  • Pull request review comment event: 219
  • Pull request event: 132
  • Pull request review event: 290
  • Fork event: 1
  • Create event: 17
Last Year
  • Issues event: 23
  • Delete event: 17
  • Issue comment event: 86
  • Push event: 487
  • Pull request review comment event: 219
  • Pull request event: 132
  • Pull request review event: 290
  • Fork event: 1
  • Create event: 17

Committers

Last synced: about 1 year ago

All Time
  • Total Commits: 1,024
  • Total Committers: 22
  • Avg Commits per committer: 46.545
  • Development Distribution Score (DDS): 0.686
Past Year
  • Commits: 115
  • Committers: 7
  • Avg Commits per committer: 16.429
  • Development Distribution Score (DDS): 0.6
Top Committers
Name Email Commits
Oliver Sanders o****s@m****k 322
Tim Pillinger t****r@m****k 245
Ronnie Dutta r****a@m****k 166
Hilary Oliver h****r@g****m 140
Mel Hall m****l@m****k 66
Bruno Kinoshita k****w@a****g 28
Matt Shin m****n@m****k 9
Sadie Bartholomew s****w@m****k 7
Tomek Trzeciak t****k@m****k 6
dependabot[bot] 4****] 6
github-actions[bot] g****s@n****m 6
David Matthews d****s@m****k 3
Douglas Lowe 1****e 3
Thomas Coleman 1****m 3
Yinjing Lin y****n@g****m 3
Alex Pletzer a****r@g****t 2
David Sutherland d****w@g****m 2
Elliot Fontaine 9****e 2
Damien François d****s@g****m 2
Neil Swart n****t@g****m 1
Mark Dawson m****n@m****k 1
Scott Wales s****s@o****u 1
Committer Domains (Top 20 + Academic)
metoffice.gov.uk: 9 outlook.com.au: 1 gokliya.net: 1 no-reply.github.com: 1 apache.org: 1

Issues and Pull Requests

Last synced: 9 months ago

All Time
  • Total issues: 96
  • Total pull requests: 390
  • Average time to close issues: over 1 year
  • Average time to close pull requests: about 1 month
  • Total issue authors: 11
  • Total pull request authors: 15
  • Average comments per issue: 1.99
  • Average comments per pull request: 1.1
  • Merged pull requests: 304
  • Bot issues: 0
  • Bot pull requests: 47
Past Year
  • Issues: 18
  • Pull requests: 139
  • Average time to close issues: 2 months
  • Average time to close pull requests: 7 days
  • Issue authors: 6
  • Pull request authors: 10
  • Average comments per issue: 0.56
  • Average comments per pull request: 0.68
  • Merged pull requests: 92
  • Bot issues: 0
  • Bot pull requests: 33
View more stats
Top Authors
Issue Authors
  • oliver-sanders (39)
  • hjoliver (31)
  • MetRonnie (5)
  • ColemanTom (5)
  • wxtim (5)
  • kinow (3)
  • sadielbartholomew (2)
  • elliotfontaine (2)
  • jfrost-mo (1)
  • benfitzpatrick (1)
  • datamel (1)
Pull Request Authors
  • oliver-sanders (126)
  • wxtim (90)
  • MetRonnie (72)
  • github-actions[bot] (43)
  • hjoliver (33)
  • ScottWales (4)
  • kinow (4)
  • elliotfontaine (4)
  • ColemanTom (3)
  • dpmatthews (3)
  • dependabot[bot] (3)
  • dwsutherland (2)
  • markgrahamdawson (2)
  • jfrost-mo (1)
  • datamel (1)
Top Labels
Issue Labels
content (71) small (9) bug (5) infrastructure (3) BLOCKED (2) hacktoberfest (2) sod-follow-up (1)
Pull Request Labels
small (107) content (87) sync (44) infrastructure (22) bug (11) dependencies (9) superseded (4) tutorials (2) wontfix (1)

Packages

  • Total packages: 2
  • Total downloads:
    • pypi 10,727 last-month
  • Total dependent packages: 6
    (may contain duplicates)
  • Total dependent repositories: 2
    (may contain duplicates)
  • Total versions: 66
  • Total maintainers: 3
pypi.org: cylc-flow

A workflow engine for cycling systems

  • Versions: 44
  • Dependent Packages: 6
  • Dependent Repositories: 1
  • Downloads: 10,409 Last month
Rankings
Dependent packages count: 1.4%
Stargazers count: 3.7%
Forks count: 4.8%
Downloads: 6.4%
Average: 7.6%
Dependent repos count: 21.6%
Maintainers (3)
wxtim oliver-sanders revilo666
Last synced: 9 months ago
pypi.org: cylc-rose

A Cylc plugin providing support for the Rose rose-suite.conf file.

  • Versions: 22
  • Dependent Packages: 0
  • Dependent Repositories: 1
  • Downloads: 318 Last month
Rankings
Forks count: 8.7%
Dependent packages count: 10.1%
Average: 16.9%
Stargazers count: 19.4%
Dependent repos count: 21.5%
Downloads: 24.9%
Maintainers (2)
wxtim oliver-sanders
Last synced: 9 months ago

Dependencies

.github/actions/install-dependencies/action.yml actions
  • conda-incubator/setup-miniconda 35d1405e78aa3f784fe3ce9a2eb378d5eeb62169 composite
.github/workflows/create-conda-envs.yml actions
  • ./.github/actions/create-conda-envs * composite
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
.github/workflows/deploy.yml actions
  • ./docs/.github/actions/create-conda-envs * composite
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • cylc/cylc-doc/.github/actions/install-dependencies master composite
  • cylc/cylc-doc/.github/actions/install-libs master composite
  • cylc/release-actions/configure-git v1 composite
.github/workflows/nightly.yml actions
  • ./docs/.github/actions/install-dependencies * composite
  • ./docs/.github/actions/install-libs * composite
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • cylc/release-actions/configure-git v1 composite
.github/workflows/shortlog.yml actions
  • actions/checkout v3 composite
  • cylc/release-actions/check-shortlog v1 composite
.github/workflows/test.yml actions
  • ./.github/actions/install-dependencies * composite
  • ./.github/actions/install-libs * composite
  • actions/checkout v3 composite
  • actions/setup-node v3 composite
  • actions/setup-python v4 composite
.github/workflows/undeploy.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • cylc/release-actions/configure-git v1 composite
.github/workflows/update_copyright.yml actions
  • actions/checkout v3 composite
  • cylc/release-actions/checkout-copyright-branch v1 composite
  • cylc/release-actions/configure-git v1 composite
  • cylc/release-actions/create-pr v1 composite
.github/actions/create-conda-envs/action.yml actions
pyproject.toml pypi