From a93d13d77bd9c7144e5271b54830b62066a8ad5f Mon Sep 17 00:00:00 2001 From: dalmijn Date: Mon, 1 Jun 2026 14:21:47 +0200 Subject: [PATCH 1/2] Docs start --- docs/_static/icon.svg | 26 ++++++++++ .../_templates/autosummary/class_pydantic.rst | 38 ++++++++++++++ docs/_templates/autosummary/module.rst | 4 ++ docs/api.rst | 7 --- docs/api/core.rst | 35 +++++++++++++ docs/api/index.rst | 29 +++++++++++ docs/api/methods.rst | 20 ++++++++ docs/api/utils.rst | 20 ++++++++ docs/conf.py | 4 +- docs/dev/index.rst | 1 - docs/index.rst | 4 +- docs/overview/index.rst | 50 +++++++++++++++++++ docs/overview/install.rst | 4 ++ docs/setup_guide/index.rst | 5 -- docs/user_guide/example.rst | 4 ++ docs/user_guide/index.rst | 6 +++ 16 files changed, 240 insertions(+), 17 deletions(-) create mode 100644 docs/_static/icon.svg create mode 100644 docs/_templates/autosummary/class_pydantic.rst create mode 100644 docs/_templates/autosummary/module.rst delete mode 100644 docs/api.rst create mode 100644 docs/api/core.rst create mode 100644 docs/api/index.rst create mode 100644 docs/api/methods.rst create mode 100644 docs/api/utils.rst create mode 100644 docs/overview/index.rst create mode 100644 docs/overview/install.rst delete mode 100644 docs/setup_guide/index.rst create mode 100644 docs/user_guide/example.rst diff --git a/docs/_static/icon.svg b/docs/_static/icon.svg new file mode 100644 index 0000000..d78e0a2 --- /dev/null +++ b/docs/_static/icon.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/_templates/autosummary/class_pydantic.rst b/docs/_templates/autosummary/class_pydantic.rst new file mode 100644 index 0000000..93c350b --- /dev/null +++ b/docs/_templates/autosummary/class_pydantic.rst @@ -0,0 +1,38 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :member-order: bysource + :class-doc-from: class + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + :nosignatures: + {% for item in methods %} + {% if item not in inherited_members %} + {%- if not item.startswith('_') %} + ~{{ name }}.{{ item }} + {%- endif -%} + {%- endif %} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + {% if item not in inherited_members %} + ~{{ name }}.{{ item }} + {%- endif %} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 0000000..0c605d9 --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,4 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + :members: diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index cfef1fb..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. currentmodule:: workflowpy - -.. _api_index: - -############# -API reference -############# diff --git a/docs/api/core.rst b/docs/api/core.rst new file mode 100644 index 0000000..9ca4e47 --- /dev/null +++ b/docs/api/core.rst @@ -0,0 +1,35 @@ +.. currentmodule:: workflowpy + +.. raw:: html + + + +.. _api_core: + +Core functionality +================== +These are the core functions & classes of workflowpy. + + +.. autosummary:: + :toctree: ../_generated + :template: autosummary/class_pydantic.rst + :nosignatures: + + Workflow + WorkflowConfig + Wildcards + Rule + Method + ExpandMethod + ReduceMethod + Parameters diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..81210cc --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,29 @@ +.. _api_index: + +============= +API reference +============= + +This is the API reference of workflowpy. + + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Section + - Information + * - :ref:`api_core` + - All core functionality of workflowpy + * - :ref:`api_methods` + - The built-in methods + * - :ref:`api_utils` + - The utiliy functions + +.. toctree:: + :maxdepth: 1 + :hidden: + + core + methods + utils diff --git a/docs/api/methods.rst b/docs/api/methods.rst new file mode 100644 index 0000000..6b26912 --- /dev/null +++ b/docs/api/methods.rst @@ -0,0 +1,20 @@ +.. currentmodule:: workflowpy.methods + +.. raw:: html + + + +.. _api_methods: + +Methods +======= +These are the built-in methods of workflowpy. diff --git a/docs/api/utils.rst b/docs/api/utils.rst new file mode 100644 index 0000000..bcb697d --- /dev/null +++ b/docs/api/utils.rst @@ -0,0 +1,20 @@ +.. currentmodule:: workflowpy.utils + +.. raw:: html + + + +.. _api_utils: + +Utility +======= +These are the utility functions of workflowpy. diff --git a/docs/conf.py b/docs/conf.py index 88126ce..6d93d93 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -89,8 +89,8 @@ def remove_dir_content(path: str) -> None: } html_css_files = ["theme.css"] -# html_favicon = "_static/icon.svg" -# html_logo = "_static/icon.svg" +html_favicon = "_static/icon.svg" +html_logo = "_static/icon.svg" html_show_sourcelink = False html_static_path = ["_static"] html_theme = "pydata_sphinx_theme" diff --git a/docs/dev/index.rst b/docs/dev/index.rst index 9c09661..85e1735 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -7,7 +7,6 @@ These pages provide guidelines on how to contribute to workflowpy. Furthermore it informs you on planned developments and new features. .. toctree:: - :caption: Table of Contents :maxdepth: 2 :hidden: diff --git a/docs/index.rst b/docs/index.rst index 2ff7745..5eccb75 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ :titlesonly: :hidden: - setup_guide/index.rst + overview/index.rst user_guide/index.rst - api.rst + api/index.rst dev/index.rst diff --git a/docs/overview/index.rst b/docs/overview/index.rst new file mode 100644 index 0000000..d5abfe2 --- /dev/null +++ b/docs/overview/index.rst @@ -0,0 +1,50 @@ +.. _overview_index: + +=============== +Getting started +=============== + +.. grid:: 2 + :gutter: 1 + + .. grid-item-card:: + :text-align: center + :link: overview_install_guide + :link-type: ref + + :octicon:`gear;10em` + +++ + Installation guide + + .. grid-item-card:: + :text-align: center + :link: user_guide_index + :link-type: ref + + :octicon:`book;10em` + +++ + User guide + + .. grid-item-card:: + :text-align: center + :link: user_guide_examples + :link-type: ref + + :octicon:`graph;10em` + +++ + Examples + + .. grid-item-card:: + :text-align: center + :link: api_index + :link-type: ref + + :octicon:`list-unordered;10em` + +++ + API reference + +.. toctree:: + :maxdepth: 2 + :hidden: + + install.rst diff --git a/docs/overview/install.rst b/docs/overview/install.rst new file mode 100644 index 0000000..66f22ef --- /dev/null +++ b/docs/overview/install.rst @@ -0,0 +1,4 @@ +.. _overview_install_guide: + +Installation guide +================== diff --git a/docs/setup_guide/index.rst b/docs/setup_guide/index.rst deleted file mode 100644 index 337d857..0000000 --- a/docs/setup_guide/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _setup_guide_index: - -=========== -Setup guide -=========== diff --git a/docs/user_guide/example.rst b/docs/user_guide/example.rst new file mode 100644 index 0000000..5a3207c --- /dev/null +++ b/docs/user_guide/example.rst @@ -0,0 +1,4 @@ +.. _user_guide_examples: + +Examples +======== diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index c88b1c0..f30b1a7 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -3,3 +3,9 @@ ========== User guide ========== + +.. toctree:: + :maxdepth: 2 + :hidden: + + example.rst From 415917e845241a5e2663efa2b3add18598e2893b Mon Sep 17 00:00:00 2001 From: dalmijn Date: Tue, 2 Jun 2026 15:58:24 +0200 Subject: [PATCH 2/2] Push docs; some progress --- .github/workflows/ci_docs.yml | 20 +++++++------- docs/api/core.rst | 22 ++++++++++++++- docs/api/index.rst | 6 ++--- docs/api/methods.rst | 22 +++++++++++++++ docs/api/utils.rst | 11 +++++++- docs/conf.py | 7 ++++- docs/links.rst | 2 ++ docs/user_guide/create.rst | 4 +++ docs/user_guide/index.rst | 48 +++++++++++++++++++++++++++++++++ docs/user_guide/term.rst | 47 ++++++++++++++++++++++++++++++++ docs/user_guide/use/create.rst | 4 +++ docs/user_guide/use/execute.rst | 4 +++ docs/user_guide/use/index.rst | 12 +++++++++ docs/user_guide/use/method.rst | 4 +++ 14 files changed, 197 insertions(+), 16 deletions(-) create mode 100644 docs/links.rst create mode 100644 docs/user_guide/create.rst create mode 100644 docs/user_guide/term.rst create mode 100644 docs/user_guide/use/create.rst create mode 100644 docs/user_guide/use/execute.rst create mode 100644 docs/user_guide/use/index.rst create mode 100644 docs/user_guide/use/method.rst diff --git a/.github/workflows/ci_docs.yml b/.github/workflows/ci_docs.yml index f1b3106..1b27bd4 100644 --- a/.github/workflows/ci_docs.yml +++ b/.github/workflows/ci_docs.yml @@ -54,13 +54,13 @@ jobs: pixi run -e docs docs-html echo "DOC_VERSION=$(pixi run --locked -e docs python -c 'from workflowpy import __version__ as v; print("dev" if "dev" in v else "v"+v.replace(".dev",""))')" >> $GITHUB_ENV - # - name: Upload to GitHub Pages - # if: ${{ github.event_name != 'pull_request' && !github.event.act }} - # uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 - # with: - # github_token: ${{ secrets.GITHUB_TOKEN }} - # publish_dir: ./docs/_build/html - # exclude_assets: .buildinfo,_sources/*,_examples/*.ipynb - # destination_dir: ./${{ env.DOC_VERSION }} - # keep_files: false - # full_commit_message: Deploy ${{ env.DOC_VERSION }} to GitHub Pages + - name: Upload to GitHub Pages + if: ${{ !github.event.act }} + uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html + exclude_assets: .buildinfo,_sources/*,_examples/*.ipynb + destination_dir: ./${{ env.DOC_VERSION }} + keep_files: false + full_commit_message: Deploy ${{ env.DOC_VERSION }} to GitHub Pages diff --git a/docs/api/core.rst b/docs/api/core.rst index 9ca4e47..fa9d43f 100644 --- a/docs/api/core.rst +++ b/docs/api/core.rst @@ -19,6 +19,8 @@ Core functionality ================== These are the core functions & classes of workflowpy. +Workflow +-------- .. autosummary:: :toctree: ../_generated @@ -27,8 +29,26 @@ These are the core functions & classes of workflowpy. Workflow WorkflowConfig - Wildcards + +Rule +---- + +.. autosummary:: + :toctree: ../_generated + :template: autosummary/class_pydantic.rst + :nosignatures: + Rule + Wildcards + +Method +------ + +.. autosummary:: + :toctree: ../_generated + :template: autosummary/class_pydantic.rst + :nosignatures: + Method ExpandMethod ReduceMethod diff --git a/docs/api/index.rst b/docs/api/index.rst index 81210cc..70ec979 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -24,6 +24,6 @@ This is the API reference of workflowpy. :maxdepth: 1 :hidden: - core - methods - utils + core.rst + methods.rst + utils.rst diff --git a/docs/api/methods.rst b/docs/api/methods.rst index 6b26912..842eb16 100644 --- a/docs/api/methods.rst +++ b/docs/api/methods.rst @@ -18,3 +18,25 @@ Methods ======= These are the built-in methods of workflowpy. + +Script Method +--------------------- + +Python scripts can directly be added to a workflow using the `ScriptMethod` class. + +.. autosummary:: + :toctree: ../_generated + :template: autosummary/class.rst + + script.ScriptMethod + +Script Method parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :toctree: ../_generated + :template: autosummary/class.rst + + script.ScriptInput + script.ScriptOutput + script.ScriptParams diff --git a/docs/api/utils.rst b/docs/api/utils.rst index bcb697d..bee668a 100644 --- a/docs/api/utils.rst +++ b/docs/api/utils.rst @@ -1,4 +1,4 @@ -.. currentmodule:: workflowpy.utils +.. currentmodule:: workflowpy .. raw:: html @@ -18,3 +18,12 @@ Utility ======= These are the utility functions of workflowpy. + +Logging +------- + +.. autosummary:: + :toctree: ../_generated + + log.setuplog + log.add_filehandler diff --git a/docs/conf.py b/docs/conf.py index 6d93d93..190efbb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -64,7 +64,7 @@ def remove_dir_content(path: str) -> None: source_suffix = ".rst" templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "links.rst"] language = "en" master_doc = "index" pygments_style = "sphinx" @@ -128,6 +128,11 @@ def remove_dir_content(path: str) -> None: remove_from_toctrees = ["_generated/*"] +# Add information to the back of every page +rst_epilog = "" +with open("links.rst") as f: + rst_epilog += f.read() + # -- Options for manual page output --------------------------------------- man_pages = [(master_doc, "workflowpy", "workflowpy Documentation", [author], 1)] diff --git a/docs/links.rst b/docs/links.rst new file mode 100644 index 0000000..e880891 --- /dev/null +++ b/docs/links.rst @@ -0,0 +1,2 @@ +.. _SnakeMake: https://snakemake.readthedocs.io/en/stable/ +.. _CWL: https://www.commonwl.org/ diff --git a/docs/user_guide/create.rst b/docs/user_guide/create.rst new file mode 100644 index 0000000..65bbd33 --- /dev/null +++ b/docs/user_guide/create.rst @@ -0,0 +1,4 @@ +.. _user_guide_create: + +Create your own +=============== diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index f30b1a7..cf8cd34 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -4,8 +4,56 @@ User guide ========== +Workflowpy's main function is to ease the creation of workflows with the help of Python. +These workflow written in Python can than be translated to workflow engines like +SnakeMake_, which can then execute the workflow. This user guide provides a quick overview +of the terminology regarding workflows, the creation and execution of workflows, +the usage of methods in workflows, and the create of your own methods/ library of methods. + +.. grid:: 4 + :gutter: 1 + + .. grid-item-card:: + :text-align: center + :link: user_guide_term + :link-type: ref + + :octicon:`list-ordered;5em` + +++ + Terminology + + .. grid-item-card:: + :text-align: center + :link: user_guide_use_index + :link-type: ref + + :octicon:`workflow;5em` + +++ + How to use + + .. grid-item-card:: + :text-align: center + :link: user_guide_create + :link-type: ref + + :octicon:`code;5em` + +++ + Create your own + + .. grid-item-card:: + :text-align: center + :link: user_guide_examples + :link-type: ref + + :octicon:`graph;5em` + +++ + Examples + .. toctree:: :maxdepth: 2 :hidden: + term.rst + use/index.rst + create.rst example.rst diff --git a/docs/user_guide/term.rst b/docs/user_guide/term.rst new file mode 100644 index 0000000..b04dc5d --- /dev/null +++ b/docs/user_guide/term.rst @@ -0,0 +1,47 @@ +.. _user_guide_term: + +Terminology +=========== + +.. glossary:: + + workflow + A workflow is a sequence of rules that are executed in a specific order. + A workflow is initialized with a root directory and optional configuration and wildcards. + Then, rules can be added to the workflow which are validated on the fly. + A workflow can be visualized using a `rulegraph` and exported to a workflow engine. + The workflow is defined using the :class:`~workflowpy.Workflow` class. + For more information see the ':ref:`user_guide_use_create`' section. + + configuration + The workflow configuration contains settings for the workflow rules which will be saved to a separate configuration file when exporting to a workflow engine. + This way the exported workflow can still to some extend be configured by the user. + A user can define the configuration using the :class:`~workflowpy.WorkflowConfig` class. + These parameters can be passed to the methods using a reference object, typically created using the + :meth:`~workflowpy.Workflow.get_ref` method. + + method + Methods define and validate the input, output, and params (parameters) of a step in the workflow. + Methods also define the logic of what is executed, which can be a simple command line call or a complex Python function. + We distinguish between normal, expand, and reduce methods, see also the ':ref:`user_guide_use_method`' section. + HydroFlows contains a library of methods focussing on flood risk assessments, but users can also define their own methods. + All methods must have a specific signature to be used in HydroFlows, + for more information see the :class:`~workflowpy.Method` class and the ':ref:`user_guide_create`' section. + + rule + A rule is a wrapper around a method to be run in the context of a workflow. + The rule is responsible for detecting wildcards and evaluating them based on the workflow wildcards. + A rule is created by adding a method to the workflow using the :meth:`~workflowpy.Workflow.create_rule` method of the workflow class. + For more information see the ':ref:`user_guide_use_create`' section. + + wildcards + Wildcards are used to create multiple instances of a method in a rule and allow for parallelization of the workflow. + Wildcards are defined with ``{}`` in the input or output file paths of a method and their values are set in the :attr:`~workflowpy.Workflow.wildcards` attribute. + Normal methods can repeated for multiple of the same input files or different values of the same param if the same wildcard is set on the input and/or params, and output files, these are called **repeat** wildcards. + Expand methods will generate a new wildcard on one or more output files to create multiple of the same output files, these are called **expand** wildcards. + Reduce methods require a wildcard on the input files to reduce over multiple of the same input files, these are called **reduce** wildcards. + For more information see the ':ref:`user_guide_use_create`' section and :class:`~workflowpy.Wildcards` class. + + engine + The workflow engine is controls the execution of the workflow. + Supported engines are the HydroFlows engine, SnakeMake_, or CWL_. diff --git a/docs/user_guide/use/create.rst b/docs/user_guide/use/create.rst new file mode 100644 index 0000000..451d8ee --- /dev/null +++ b/docs/user_guide/use/create.rst @@ -0,0 +1,4 @@ +.. _user_guide_use_create: + +Create a workflow +================= diff --git a/docs/user_guide/use/execute.rst b/docs/user_guide/use/execute.rst new file mode 100644 index 0000000..6956158 --- /dev/null +++ b/docs/user_guide/use/execute.rst @@ -0,0 +1,4 @@ +.. _user_guide_use_execute: + +Execute a workflow +================== diff --git a/docs/user_guide/use/index.rst b/docs/user_guide/use/index.rst new file mode 100644 index 0000000..a217b8f --- /dev/null +++ b/docs/user_guide/use/index.rst @@ -0,0 +1,12 @@ +.. _user_guide_use_index: + +How to use +========== + +.. toctree:: + :maxdepth: 2 + :hidden: + + create.rst + method.rst + execute.rst diff --git a/docs/user_guide/use/method.rst b/docs/user_guide/use/method.rst new file mode 100644 index 0000000..dafcf0f --- /dev/null +++ b/docs/user_guide/use/method.rst @@ -0,0 +1,4 @@ +.. _user_guide_use_method: + +Working with methods +====================