Skip to content
forked from cylc/cylc-doc

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

License

Notifications You must be signed in to change notification settings

datamel/cylc-doc

 
 

Repository files navigation

Cylc Documentation

stable latest nightly

Documentation for the Cylc Workflow Engine and its software ecosystem.

Writing

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

We use the following convention for underlining headings:

Heading
=======

Sub Heading
-----------

Sub Sub Heading
^^^^^^^^^^^^^^^

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

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::

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.

Development

test nightly

Installation

Note: you may need to install graphviz first (e.g. conda install graphviz).

$ git clone [email protected]:cylc/cylc-doc.git cylc-doc
$ cd cylc-doc
$ pip install -e .

Simple Build

Build the docs using make:

$ make html

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

$ make clean html

Automatic Build

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

$ pip install -e .[watch]

Then build the watch target:

$ 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:

$ 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

# note: -W tells Sphinx to fail on warnings
$ make html linkcheck doctest SPHINXOPTS='-W'

Deploying

To document a new version of Cylc:

  • Create a tag with a name matching a released cylc-flow tag.
  • Push it to cylc/cylc-doc.
  • Trigger the deploy workflow against that tag.

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

  • Update the existing tag.
  • Push it to cylc/cylc-doc.
  • 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-2022 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.

About

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

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 79.9%
  • Shell 7.8%
  • Makefile 7.6%
  • CSS 2.5%
  • HTML 2.2%