cylc / cylc-sphinx-extensions Goto Github PK

View Code? Open in Web Editor NEW

4.0 4.0 8.0 6.61 MB

Sphinx extensions for documenting Cylc projects.

Home Page: https://cylc.github.io/cylc-sphinx-extensions/

License: GNU General Public License v3.0

Makefile 0.59% Python 77.10% CSS 6.30% JavaScript 16.01%

cylc sphinx

cylc-sphinx-extensions's Introduction

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

Copyright and Terms of Use

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

Contributions welcome:

Read the contributing page.
Development setup instructions are in the developer docs.
Involved change proposals can be found in the admin pages.
Touch base in the developers chat.

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

cylc-sphinx-extensions's People

Contributors

Stargazers

Watchers

Forkers

oliver-sanders sadielbartholomew wxtim kinow datamel dpmatthews metronnie hjoliver

cylc-sphinx-extensions's Issues

minicylc: fix for non-firefox browsers

See #71 (review)

cylc_lang: nested meta sections

Low priority bug (more a limitation than a bug) easier just to document for now in the (hopefully) unlikely case that we will need this (famous last words I will likely eat if we start giving Cylc plugins configuration sections...).

As of #50 only settings explicitly defined in meta sections are documented.

Example:

[platforms]
    [[<platform name>]]
        host
       [[[selection]]]
           method

    [[localhost]]
        host = localhost

The above example will document fine, the overwritten host setting will appear correctly.

However, if we wanted to overwrite the [selection]method for localhost that would not appear in the docs.

I think fixing this would require making cylc.flow.parsec.config.ConfigNode.walk aware of the meta keyword.

See #50

update cylc lexer to graphing changes

The changes in these PRs will break the support for graph string syntax highlighting in cylc_lang:

docutils 0.16.0

A strange issue has cropped up in the slides build (hieroglyph).

Probably an interaction between:

Sphinx
Docutils
Auto Summary
Hieroglyph

The issue is that a reference(?) to hieroglyph_addons is resolved to hieroglyph\x00_addons. Why this should affect hieroglyph_addons and not hieroglyph_patch I do not know. Renaming the extension does not seem to shift the issue. I think it is the reference inserted by autosummary which is causing the failure.

See #13 (comment)

At the moment the workaround is to pi docutils to < 0.16.0 which is a nasty solution.

cylc_lang: add full confuiguration name to each section in the autodocumenter

See cylc/cylc-doc#158

Add the full name of the configuration into the docs for the configuration to make navigation a little easier something like this:

.. cylc:conf:: whatever

   :global.cylc[a][b]whatevter:  <= Add this
   :default: foo

    Content

Conditional expressions
Cycling (with subgraphs)
Suicide Triggers
Parametrisation

Issue migrated from cylc/cylc-doc#11

tree: extension for displaying file hierarchies

Implement an extension for elegantly displaying information of the format:

 foo/
  |-- bar          # some description here
  \-- baz/         # the stuff in this directory does x
       |-- pub     # this file does y
       `-- qux     # whatever

publish on pypi

extension to auto-document Cylc workflows from [meta] sections

Cylc workflows can be documented using [meta] sections.

We plan to integrate this information into the Cylc UI soon: cylc/cylc-ui#1071

However there are other cases where this information might be useful, e.g. for projects wishing to build Sphinx documentation for their workflows.

We should look at writing a simple Sphinx autodocumenter to make this easier.

cylc domain

Add a sphinx domain for cylc configurations.

find somewhere to put the built documentation

see #2