From ca5b2f894c174b6920b455261883d276e9096649 Mon Sep 17 00:00:00 2001 From: Marco Donadoni Date: Wed, 7 Feb 2024 16:26:25 +0100 Subject: [PATCH] refactor(docs): move from reST to Markdown (#441) Convert docs from reStructuredText to Markdown so that the changelog file is compatible with Release Please. --- AUTHORS.md | 16 ++++ AUTHORS.rst | 17 ---- CHANGELOG.md | 104 +++++++++++++++++++++++ CHANGES.rst | 123 ---------------------------- CONTRIBUTING.rst => CONTRIBUTING.md | 12 ++- MANIFEST.in | 3 +- README.md | 35 ++++++++ README.rst | 55 ------------- docs/conf.py | 8 +- docs/index.md | 31 +++++++ docs/index.rst | 28 ------- setup.py | 6 +- 12 files changed, 202 insertions(+), 236 deletions(-) create mode 100644 AUTHORS.md delete mode 100644 AUTHORS.rst delete mode 100644 CHANGES.rst rename CONTRIBUTING.rst => CONTRIBUTING.md (73%) create mode 100644 README.md delete mode 100644 README.rst create mode 100644 docs/index.md delete mode 100644 docs/index.rst diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..1144e38 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,16 @@ +# Authors + +The list of contributors in alphabetical order: + +- [Adelina Lintuluoto](https://orcid.org/0000-0002-0726-1452) +- [Agisilaos Kounelis](https://orcid.org/0000-0001-9312-3189) +- [Audrius Mecionis](https://orcid.org/0000-0002-3759-1663) +- [Camila Diaz](https://orcid.org/0000-0001-5543-797X) +- [Daniel Prelipcean](https://orcid.org/0000-0002-4855-194X) +- [Diego Rodriguez](https://orcid.org/0000-0003-0649-2002) +- [Dinos Kousidis](https://orcid.org/0000-0002-4914-4289) +- [Jan Okraska](https://orcid.org/0000-0002-1416-3244) +- [Marco Vidal](https://orcid.org/0000-0002-9363-4971) +- [Rokas Maciulaitis](https://orcid.org/0000-0003-1064-6967) +- [Sinclert Perez](https://www.linkedin.com/in/sinclert) +- [Tibor Simko](https://orcid.org/0000-0001-7202-5803) diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index 7a89429..0000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,17 +0,0 @@ -Authors -======= - -The list of contributors in alphabetical order: - -- `Adelina Lintuluoto `_ -- `Agisilaos Kounelis `_ -- `Audrius Mecionis `_ -- `Camila Diaz `_ -- `Daniel Prelipcean `_ -- `Diego Rodriguez `_ -- `Dinos Kousidis `_ -- `Jan Okraska `_ -- `Marco Vidal `_ -- `Rokas Maciulaitis `_ -- `Sinclert Perez `_ -- `Tibor Simko `_ diff --git a/CHANGELOG.md b/CHANGELOG.md index e69de29..8d3888a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -0,0 +1,104 @@ +# Changelog + +## 0.9.2 (2023-12-12) + +- Adds automated multi-platform container image building for amd64 and arm64 architectures. +- Adds metadata labels to Dockerfile. +- Fixes container image building on the arm64 architecture. + +## 0.9.1 (2023-09-27) + +- Fixes container image names to be Podman-compatible. + +## 0.9.0 (2023-01-19) + +- Adds support for specifying `slurm_partition` and `slurm_time` for Slurm compute backend jobs. +- Adds support for Kerberos authentication for workflow orchestration. +- Adds support for Rucio authentication for workflow jobs. +- Changes the base image of the component to Ubuntu 20.04 LTS and reduces final Docker image size by removing build-time dependencies. + +## 0.8.1 (2022-02-07) + +- Adds support for specifying `kubernetes_job_timeout` for Kubernetes compute backend jobs. +- Fixes workflow stuck in pending status due to early engine fail. + +## 0.8.0 (2021-11-22) + +- Adds support for custom workspace paths. + +## 0.7.5 (2021-07-05) + +- Changes internal dependencies to remove click. + +## 0.7.4 (2021-04-28) + +- Adds support for specifying `kubernetes_memory_limit` for Kubernetes compute backend jobs. + +## 0.7.3 (2021-03-17) + +- Changes workflow engine instantiation to use central REANA-Commons factory. +- Changes job command strings by removing interpreter and using central REANA-Commons job command serialisation. +- Changes status `succeeded` to `finished` to use central REANA nomenclature. + +## 0.7.2 (2021-02-03) + +- Fixes minor code warnings. +- Changes CI system to include Python flake8 and Dockerfile hadolint checkers. + +## 0.7.1 (2020-11-10) + +- Adds support for specifying `htcondor_max_runtime` and `htcondor_accounting_group` for HTCondor compute backend jobs. + +## 0.7.0 (2020-10-20) + +- Adds possibility to execute workflow from specified step. +- Adds option to specify unpacked Docker images as workflow step requirement. +- Adds option to specify Kubernetes UID for jobs. +- Adds support for VOMS proxy as a new authentication method. +- Adds pinning of all Python dependencies allowing to easily rebuild component images at later times. +- Changes base image to use Python 3.8. +- Changes code formatting to respect `black` coding style. +- Changes documentation to single-page layout. + +## 0.6.1 (2020-05-25) + +- Upgrades REANA-Commons package using latest Kubernetes Python client version. + +## 0.6.0 (2019-12-20) + +- Allows to specify compute backend (HTCondor, Kubernetes or Slurm) and + Kerberos authentication requirement for Serial workflow jobs. +- Allows partial workflow execution until step specified by the user. +- Moves workflow engine to the same Kubernetes pod with the REANA-Job-Controller + (sidecar pattern). + +## 0.5.0 (2019-04-23) + +- Makes workflow engine independent of Celery so that independent workflow + instances are created on demand for each user. +- Replaces `api_client` module with centralised one from REANA-Commons. +- Introduces CVMFS mounts in job specifications. +- Makes docker image slimmer by using `python:3.6-slim`. +- Centralises log level and log format configuration. + +## 0.4.0 (2018-11-06) + +- Improves AMQP re-connection handling. Switches from `pika` to `kombu`. +- Utilises common openapi client for communication with REANA-Job-Controller. +- Changes license to MIT. + +## 0.3.2 (2018-09-25) + +- Modifies OS related commands for CephFS compatibility. + +## 0.3.1 (2018-09-07) + +- Adds parameter passing to workflow steps. +- Adds user guide and getting started sections to the documentation. + +## 0.3.0 (2018-08-10) + +- Initial public release. +- Executes serial workflows. +- Tracks progress of workflow runs. +- Caches job results by default. diff --git a/CHANGES.rst b/CHANGES.rst deleted file mode 100644 index 7b3227f..0000000 --- a/CHANGES.rst +++ /dev/null @@ -1,123 +0,0 @@ -Changes -======= - -Version 0.9.2 (2023-12-12) --------------------------- - -- Adds automated multi-platform container image building for amd64 and arm64 architectures. -- Adds metadata labels to Dockerfile. -- Fixes container image building on the arm64 architecture. - -Version 0.9.1 (2023-09-27) --------------------------- - -- Fixes container image names to be Podman-compatible. - -Version 0.9.0 (2023-01-19) --------------------------- - -- Adds support for specifying ``slurm_partition`` and ``slurm_time`` for Slurm compute backend jobs. -- Adds support for Kerberos authentication for workflow orchestration. -- Adds support for Rucio authentication for workflow jobs. -- Changes the base image of the component to Ubuntu 20.04 LTS and reduces final Docker image size by removing build-time dependencies. - -Version 0.8.1 (2022-02-07) --------------------------- - -- Adds support for specifying ``kubernetes_job_timeout`` for Kubernetes compute backend jobs. -- Fixes workflow stuck in pending status due to early engine fail. - -Version 0.8.0 (2021-11-22) --------------------------- - -- Adds support for custom workspace paths. - -Version 0.7.5 (2021-07-05) --------------------------- - -- Changes internal dependencies to remove click. - -Version 0.7.4 (2021-04-28) --------------------------- - -- Adds support for specifying ``kubernetes_memory_limit`` for Kubernetes compute backend jobs. - -Version 0.7.3 (2021-03-17) --------------------------- - -- Changes workflow engine instantiation to use central REANA-Commons factory. -- Changes job command strings by removing interpreter and using central REANA-Commons job command serialisation. -- Changes status ``succeeded`` to ``finished`` to use central REANA nomenclature. - -Version 0.7.2 (2021-02-03) --------------------------- - -- Fixes minor code warnings. -- Changes CI system to include Python flake8 and Dockerfile hadolint checkers. - -Version 0.7.1 (2020-11-10) --------------------------- - -- Adds support for specifying ``htcondor_max_runtime`` and ``htcondor_accounting_group`` for HTCondor compute backend jobs. - -Version 0.7.0 (2020-10-20) --------------------------- - -- Adds possibility to execute workflow from specified step. -- Adds option to specify unpacked Docker images as workflow step requirement. -- Adds option to specify Kubernetes UID for jobs. -- Adds support for VOMS proxy as a new authentication method. -- Adds pinning of all Python dependencies allowing to easily rebuild component images at later times. -- Changes base image to use Python 3.8. -- Changes code formatting to respect ``black`` coding style. -- Changes documentation to single-page layout. - -Version 0.6.1 (2020-05-25) --------------------------- - -- Upgrades REANA-Commons package using latest Kubernetes Python client version. - -Version 0.6.0 (2019-12-20) --------------------------- - -- Allows to specify compute backend (HTCondor, Kubernetes or Slurm) and - Kerberos authentication requirement for Serial workflow jobs. -- Allows partial workflow execution until step specified by the user. -- Moves workflow engine to the same Kubernetes pod with the REANA-Job-Controller - (sidecar pattern). - -Version 0.5.0 (2019-04-23) --------------------------- - -- Makes workflow engine independent of Celery so that independent workflow - instances are created on demand for each user. -- Replaces ``api_client`` module with centralised one from REANA-Commons. -- Introduces CVMFS mounts in job specifications. -- Makes docker image slimmer by using ``python:3.6-slim``. -- Centralises log level and log format configuration. - -Version 0.4.0 (2018-11-06) --------------------------- - -- Improves AMQP re-connection handling. Switches from ``pika`` to ``kombu``. -- Utilises common openapi client for communication with REANA-Job-Controller. -- Changes license to MIT. - -Version 0.3.2 (2018-09-25) --------------------------- - -- Modifies OS related commands for CephFS compatibility. - -Version 0.3.1 (2018-09-07) --------------------------- - -- Adds parameter passing to workflow steps. -- Adds user guide and getting started sections to the documentation. - -Version 0.3.0 (2018-08-10) --------------------------- - -- Initial public release. -- Executes serial workflows. -- Tracks progress of workflow runs. -- Caches job results by default. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.md similarity index 73% rename from CONTRIBUTING.rst rename to CONTRIBUTING.md index 43aa322..b98091d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.md @@ -1,11 +1,9 @@ -Contributing -============ +# Contributing Bug reports, issues, feature requests, and other contributions are welcome. If you find a demonstrable problem that is caused by the REANA code, please: -1. Search for `already reported problems - `_. +1. Search for [already reported problems](https://github.com/reanahub/reana-workflow-engine-serial/issues). 2. Check if the issue has been fixed or is still reproducible on the latest `master` branch. 3. Create an issue, ideally with **a test case**. @@ -13,8 +11,8 @@ a demonstrable problem that is caused by the REANA code, please: If you create a pull request fixing a bug or implementing a feature, you can run the tests to ensure that everything is operating correctly: -.. code-block:: console - - $ ./run-tests.sh +```console +$ ./run-tests.sh +``` Each pull request should preserve or increase code coverage. diff --git a/MANIFEST.in b/MANIFEST.in index af58b61..b8e8647 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -6,7 +6,6 @@ include *.json include *.md -include *.rst include *.sh include *.txt include *.yaml @@ -21,6 +20,6 @@ recursive-include reana_workflow_engine_serial *.py recursive-include reana_workflow_engine_serial *.json recursive-include docs *.py recursive-include docs *.png -recursive-include docs *.rst +recursive-include docs *.md recursive-include docs *.txt recursive-include tests *.py diff --git a/README.md b/README.md new file mode 100644 index 0000000..bd777b1 --- /dev/null +++ b/README.md @@ -0,0 +1,35 @@ +# REANA-Workflow-Engine-Serial + +[![image](https://github.com/reanahub/reana-workflow-engine-serial/workflows/CI/badge.svg)](https://github.com/reanahub/reana-workflow-engine-serial/actions) +[![image](https://readthedocs.org/projects/reana-workflow-engine-serial/badge/?version=latest)](https://reana-workflow-engine-serial.readthedocs.io/en/latest/?badge=latest) +[![image](https://codecov.io/gh/reanahub/reana-workflow-engine-serial/branch/master/graph/badge.svg)](https://codecov.io/gh/reanahub/reana-workflow-engine-serial) +[![image](https://img.shields.io/badge/discourse-forum-blue.svg)](https://forum.reana.io) +[![image](https://img.shields.io/github/license/reanahub/reana-workflow-engine-serial.svg)](https://github.com/reanahub/reana-workflow-engine-serial/blob/master/LICENSE) +[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) + +## About + +REANA-Workflow-Engine-Serial is a component of the [REANA](http://www.reana.io/) reusable +and reproducible research data analysis platform. It takes care of instantiating, +executing and managing simple sequential computational workflows. + +## Features + +- Run sequential workflows consisting of Bash commands. +- Cache workflow steps by default to shorten computation time. + +## Usage + +The detailed information on how to install and use REANA can be found in +[docs.reana.io](https://docs.reana.io). + +## Useful links + +- [REANA project home page](http://www.reana.io/) +- [REANA user documentation](https://docs.reana.io) +- [REANA user support forum](https://forum.reana.io) +- [REANA-Workflow-Engine-Serial releases](https://reana-workflow-engine-serial.readthedocs.io/en/latest#changes) +- [REANA-Workflow-Engine-Serial docker images](https://hub.docker.com/r/reanahub/reana-workflow-engine-serial) +- [REANA-Workflow-Engine-Serial developer documentation](https://reana-workflow-engine-serial.readthedocs.io/) +- [REANA-Workflow-Engine-Serial known issues](https://github.com/reanahub/reana-workflow-engine-serial/issues) +- [REANA-Workflow-Engine-Serial source code](https://github.com/reanahub/reana-workflow-engine-serial) diff --git a/README.rst b/README.rst deleted file mode 100644 index 4e060b6..0000000 --- a/README.rst +++ /dev/null @@ -1,55 +0,0 @@ -############################ -REANA-Workflow-Engine-Serial -############################ - -.. image:: https://github.com/reanahub/reana-workflow-engine-serial/workflows/CI/badge.svg - :target: https://github.com/reanahub/reana-workflow-engine-serial/actions - -.. image:: https://readthedocs.org/projects/reana-workflow-engine-serial/badge/?version=latest - :target: https://reana-workflow-engine-serial.readthedocs.io/en/latest/?badge=latest - -.. image:: https://codecov.io/gh/reanahub/reana-workflow-engine-serial/branch/master/graph/badge.svg - :target: https://codecov.io/gh/reanahub/reana-workflow-engine-serial - -.. image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/reanahub/reana?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge - -.. image:: https://img.shields.io/github/license/reanahub/reana-workflow-engine-serial.svg - :target: https://github.com/reanahub/reana-workflow-engine-serial/blob/master/LICENSE - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - -About -===== - -REANA-Workflow-Engine-Serial is a component of the `REANA -`_ reusable and reproducible research data analysis -platform. It takes care of instantiating, executing and managing simple -sequential computational workflows. - -Features -======== - -- Run sequential workflows consisting of Bash commands. -- Cache workflow steps by default to shorten computation time. - -Usage -===== - -The detailed information on how to install and use REANA can be found in -`docs.reana.io `_. - - -Useful links -============ - -- `REANA project home page `_ -- `REANA user documentation `_ -- `REANA user support forum `_ - -- `REANA-Workflow-Engine-Serial releases `_ -- `REANA-Workflow-Engine-Serial docker images `_ -- `REANA-Workflow-Engine-Serial developer documentation `_ -- `REANA-Workflow-Engine-Serial known issues `_ -- `REANA-Workflow-Engine-Serial source code `_ diff --git a/docs/conf.py b/docs/conf.py index 43a9d37..13ebf8d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,6 +40,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.doctest", @@ -55,14 +56,17 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +source_suffix = [".rst", ".md"] + +# Allow using ::: in Markdown files +myst_enable_extensions = ["colon_fence"] # The master toctree document. master_doc = "index" # General information about the project. project = "reana" -copyright = "2018-2023, info@reana.io" +copyright = "2018-2024, info@reana.io" author = "info@reana.io" # The version info for the project you're documenting, acts as replacement for diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..0e2ee52 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,31 @@ +```{include} ../README.md +:end-before: "## About" +``` + +```{include} ../README.md +:start-after: "## About" +:end-before: "## Useful links" + +``` + +```{include} ../CHANGELOG.md +:heading-offset: 1 +``` + +```{include} ../CONTRIBUTING.md +:heading-offset: 1 +``` + +## License + +```{eval-rst} +.. include:: ../LICENSE +``` + +In applying this license, CERN does not waive the privileges and immunities +granted to it by virtue of its status as an Intergovernmental Organization or +submit itself to any jurisdiction. + +```{include} ../AUTHORS.md +:heading-offset: 1 +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index e89f215..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. include:: ../README.rst - :end-before: About - -.. include:: ../README.rst - :start-after: ===== - :end-before: Features - -Features: - -.. include:: ../README.rst - :start-line: 33 - :end-before: Useful links - - -.. include:: ../CHANGES.rst - -.. include:: ../CONTRIBUTING.rst - -License -======= - -.. include:: ../LICENSE - -In applying this license, CERN does not waive the privileges and immunities -granted to it by virtue of its status as an Intergovernmental Organization or -submit itself to any jurisdiction. - -.. include:: ../AUTHORS.rst diff --git a/setup.py b/setup.py index 8bd2a27..059ce2e 100755 --- a/setup.py +++ b/setup.py @@ -15,8 +15,8 @@ from setuptools import find_packages, setup -readme = open("README.rst").read() -history = open("CHANGES.rst").read() +readme = open("README.md").read() +history = open("CHANGELOG.md").read() tests_require = [ "pytest-reana>=0.9.2,<0.10.0", @@ -29,6 +29,7 @@ "Flask-DebugToolbar", ], "docs": [ + "myst-parser", "Sphinx>=1.5.1", "sphinx-rtd-theme>=0.1.9", "Jinja2<3.1", @@ -64,6 +65,7 @@ version=version, description=__doc__, long_description=readme + "\n\n" + history, + long_description_content_type="text/markdown", author="REANA", author_email="info@reana.io", url="https://github.com/reanahub/reana-workflow-engine-serial",