From 4732884a3da52694fb86d72873eceef3ad2deb27 Mon Sep 17 00:00:00 2001 From: Marco Donadoni Date: Wed, 7 Feb 2024 14:20:34 +0100 Subject: [PATCH] refactor(docs): move from reST to Markdown (#428) Convert docs from reStructuredText to Markdown so that the changelog file is compatible with Release Please. --- AUTHORS.md | 14 +++ AUTHORS.rst | 15 --- CHANGELOG.md | 161 ++++++++++++++++++++++++ CHANGES.rst | 189 ---------------------------- CONTRIBUTING.rst => CONTRIBUTING.md | 12 +- MANIFEST.in | 3 +- README.md | 35 ++++++ README.rst | 53 -------- docs/conf.py | 8 +- docs/index.md | 107 ++++++++++++++++ docs/index.rst | 97 -------------- setup.py | 6 +- 12 files changed, 333 insertions(+), 367 deletions(-) create mode 100644 AUTHORS.md delete mode 100644 AUTHORS.rst delete mode 100644 CHANGES.rst rename CONTRIBUTING.rst => CONTRIBUTING.md (74%) 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 00000000..e05e7dc4 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,14 @@ +# 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) +- [Anton Khodak](https://orcid.org/0000-0003-3263-4553) +- [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 Donadoni](https://orcid.org/0000-0003-2922-5505) +- [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 5773ca4c..00000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,15 +0,0 @@ -Authors -======= - -The list of contributors in alphabetical order: - -- `Adelina Lintuluoto `_ -- `Agisilaos Kounelis `_ -- `Anton Khodak `_ -- `Diego Rodriguez `_ -- `Dinos Kousidis `_ -- `Jan Okraska `_ -- `Marco Donadoni `_ -- `Rokas Maciulaitis `_ -- `Sinclert Perez `_ -- `Tibor Simko `_ diff --git a/CHANGELOG.md b/CHANGELOG.md index e69de29b..18b84e81 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -0,0 +1,161 @@ +# Changelog + +## 0.9.2 (2023-12-12) + +- Adds metadata labels to Dockerfile. +- Adds automated multi-platform container image building for amd64 and arm64 architectures. +- Changes CVMFS support to allow users to automatically mount any available repository. +- Fixes container image building on the arm64 architecture. +- Fixes the creation of Kubernetes jobs by retrying in case of error and by correctly handling the error after reaching the retry limit. +- Fixes job monitoring in cases when job creation fails, for example when it is not possible to successfully mount volumes. + +## 0.9.1 (2023-09-27) + +- Adds unique error messages to Kubernetes job monitor to more easily identify source of problems. +- Changes Paramiko to version 3.0.0. +- Changes HTCondor to version 9.0.17 (LTS). +- Changes Rucio authentication helper to version 1.1.1 allowing users to override the Rucio server and authentication hosts independently of VO name. +- Fixes intermittent Slurm connection issues by DNS-resolving the Slurm head node IPv4 address before establishing connections. +- Fixes deletion of failed jobs not being performed when Kerberos is enabled. +- Fixes job monitoring to consider OOM-killed jobs as failed. +- Fixes Slurm command generation issues when using fully-qualified image names. +- Fixes location of HTCondor build dependencies. +- Fixes detection of default Rucio server and authentication host for ATLAS VO. +- Fixes container image names to be Podman-compatible. + +## 0.9.0 (2023-01-20) + +- Adds support for Rucio authentication for workflow jobs. +- Adds support for specifying `slurm_partition` and `slurm_time` for Slurm compute backend jobs. +- Adds Kerberos sidecar container to renew ticket periodically for long-running jobs. +- Changes `reana-auth-vomsproxy` sidecar to the latest stable version to support client-side proxy file generation technique and ESCAPE VOMS. +- Changes default Slurm partition to `inf-short`. +- Changes to PostgreSQL 12.13. +- 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. +- Adds a new condition to allow processing jobs in case of receiving multiple failed events when job containers are not in a running state. + +## 0.8.0 (2021-11-22) + +- Adds database connection closure after each REST API request. +- Adds labels to job and run-batch pods to reduce k8s events to listen to for `job-monitor`. +- Fixes auto-mounting of Kubernetes API token inside user jobs by disabling it. +- Changes job dispatching to use only job-specific node labels. +- Changes to PostgreSQL 12.8. + +## 0.7.5 (2021-07-05) + +- Changes HTCondor to 8.9.11. +- Changes myschedd package and configuration to latest versions. +- Fixes job command formatting bug for CWL workflows on HTCondor. + +## 0.7.4 (2021-04-28) + +- Adds configuration environment variable to set job memory limits for the Kubernetes compute backend (`REANA_KUBERNETES_JOBS_MEMORY_LIMIT`). +- Fixes Kubernetes job log capture to include information about failures caused by external factors such as OOMKilled. +- Adds support for specifying `kubernetes_memory_limit` for Kubernetes compute backend jobs. + +## 0.7.3 (2021-03-17) + +- Adds new configuration to toggle Kubernetes user jobs clean up. +- Fixes HTCondor Docker networking and machine version requirement setup. +- Fixes HTCondor logs and workspace files retrieval on job failure. +- Fixes Slurm job submission providing the correct shell environment to run Singularity. +- Changes HTCondor myschedd to the latest version. +- Changes job status `succeeded` to `finished` to use central REANA nomenclature. +- Changes how to deserialise job commands using central REANA-Commons deserialiser function. + +## 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. +- Fixes Docker build by properly exiting when there are problems with `myschedd` installation. + +## 0.7.0 (2020-10-20) + +- Adds support for running unpacked Docker images from CVMFS on HTCondor jobs. +- Adds support for pulling private images using image pull secrets. +- 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. +- Fixes HTCondor job submission retry technique. +- Changes error reporting on Docker image related failures. +- Changes runtime pods to prefix user workflows with the configured REANA prefix. +- Changes CVMFS to be read-only mount. +- Changes runtime job instantiation into the configured runtime namespace. +- Changes test suite to enable running tests locally also on macOS platform. +- Changes CERN HTCondor compute backend to use the new `myschedd` connection library. +- Changes CERN Slurm compute backend to improve job status detection. +- 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) + +- Adds generic job manager class and provides example classes for CERN HTCondor + and CERN Slurm clusters. +- Moves job controller to the same Kubernetes pod with the + REANA-Workflow-Engine-\* (sidecar pattern). +- Adds sidecar container to the Kubernetes job pod if Kerberos authentication + is required. +- Provides user secrets to the job container runtime tasks. +- Refactors job monitoring using singleton pattern. + +## 0.5.1 (2019-04-23) + +- Pins `urllib3` due to a conflict while installing `Kubernetes` Python + library. +- Fixes documenation build badge. + +## 0.5.0 (2019-04-23) + +- Adds a new endpoint to delete jobs (Kubernetes). +- Introduces new common interface for job management which defines what the + compute backends should offer to be compatible with REANA, currently only + Kubernetes backend is supported. +- Fixes security vulnerability which allowed users to access other people's + workspaces. +- Makes CVMFS mounts optional and configurable at repository level. +- Updates the creation of CVMFS volumes specification, it now uses normal + persistent volume claims. +- Increases stability and improves test coverage. + +## 0.4.0 (2018-11-06) + +- Improves REST API documentation rendering. +- Changes license to MIT. + +## 0.3.2 (2018-09-26) + +- Adapts Kubernetes API adaptor to mount shared volumes on jobs as CEPH + `persistentVolumeClaim`'s (managed by `reana-cluster`) instead of plain + CEPH volumes. + +## 0.3.1 (2018-09-07) + +- Pins REANA-Commons and REANA-DB dependencies. + +## 0.3.0 (2018-08-10) + +- Adds uwsgi for production deployments. +- Switches from pykube to official Kubernetes python client. +- Adds compatibility with latest Kubernetes. + +## 0.2.0 (2018-04-19) + +- Adds dockerignore file to ease developments. + +## 0.1.0 (2018-01-30) + +- Initial public release. + diff --git a/CHANGES.rst b/CHANGES.rst deleted file mode 100644 index bd3d373c..00000000 --- a/CHANGES.rst +++ /dev/null @@ -1,189 +0,0 @@ -Changes -======= - -Version 0.9.2 (2023-12-12) --------------------------- - -- Adds metadata labels to Dockerfile. -- Adds automated multi-platform container image building for amd64 and arm64 architectures. -- Changes CVMFS support to allow users to automatically mount any available repository. -- Fixes container image building on the arm64 architecture. -- Fixes the creation of Kubernetes jobs by retrying in case of error and by correctly handling the error after reaching the retry limit. -- Fixes job monitoring in cases when job creation fails, for example when it is not possible to successfully mount volumes. - -Version 0.9.1 (2023-09-27) --------------------------- - -- Adds unique error messages to Kubernetes job monitor to more easily identify source of problems. -- Changes Paramiko to version 3.0.0. -- Changes HTCondor to version 9.0.17 (LTS). -- Changes Rucio authentication helper to version 1.1.1 allowing users to override the Rucio server and authentication hosts independently of VO name. -- Fixes intermittent Slurm connection issues by DNS-resolving the Slurm head node IPv4 address before establishing connections. -- Fixes deletion of failed jobs not being performed when Kerberos is enabled. -- Fixes job monitoring to consider OOM-killed jobs as failed. -- Fixes Slurm command generation issues when using fully-qualified image names. -- Fixes location of HTCondor build dependencies. -- Fixes detection of default Rucio server and authentication host for ATLAS VO. -- Fixes container image names to be Podman-compatible. - -Version 0.9.0 (2023-01-20) --------------------------- - -- Adds support for Rucio authentication for workflow jobs. -- Adds support for specifying ``slurm_partition`` and ``slurm_time`` for Slurm compute backend jobs. -- Adds Kerberos sidecar container to renew ticket periodically for long-running jobs. -- Changes ``reana-auth-vomsproxy`` sidecar to the latest stable version to support client-side proxy file generation technique and ESCAPE VOMS. -- Changes default Slurm partition to ``inf-short``. -- Changes to PostgreSQL 12.13. -- 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. -- Adds a new condition to allow processing jobs in case of receiving multiple failed events when job containers are not in a running state. - -Version 0.8.0 (2021-11-22) --------------------------- - -- Adds database connection closure after each REST API request. -- Adds labels to job and run-batch pods to reduce k8s events to listen to for ``job-monitor``. -- Fixes auto-mounting of Kubernetes API token inside user jobs by disabling it. -- Changes job dispatching to use only job-specific node labels. -- Changes to PostgreSQL 12.8. - -Version 0.7.5 (2021-07-05) --------------------------- - -- Changes HTCondor to 8.9.11. -- Changes myschedd package and configuration to latest versions. -- Fixes job command formatting bug for CWL workflows on HTCondor. - -Version 0.7.4 (2021-04-28) --------------------------- - -- Adds configuration environment variable to set job memory limits for the Kubernetes compute backend (``REANA_KUBERNETES_JOBS_MEMORY_LIMIT``). -- Fixes Kubernetes job log capture to include information about failures caused by external factors such as OOMKilled. -- Adds support for specifying ``kubernetes_memory_limit`` for Kubernetes compute backend jobs. - -Version 0.7.3 (2021-03-17) --------------------------- - -- Adds new configuration to toggle Kubernetes user jobs clean up. -- Fixes HTCondor Docker networking and machine version requirement setup. -- Fixes HTCondor logs and workspace files retrieval on job failure. -- Fixes Slurm job submission providing the correct shell environment to run Singularity. -- Changes HTCondor myschedd to the latest version. -- Changes job status ``succeeded`` to ``finished`` to use central REANA nomenclature. -- Changes how to deserialise job commands using central REANA-Commons deserialiser function. - -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. -- Fixes Docker build by properly exiting when there are problems with ``myschedd`` installation. - -Version 0.7.0 (2020-10-20) --------------------------- - -- Adds support for running unpacked Docker images from CVMFS on HTCondor jobs. -- Adds support for pulling private images using image pull secrets. -- 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. -- Fixes HTCondor job submission retry technique. -- Changes error reporting on Docker image related failures. -- Changes runtime pods to prefix user workflows with the configured REANA prefix. -- Changes CVMFS to be read-only mount. -- Changes runtime job instantiation into the configured runtime namespace. -- Changes test suite to enable running tests locally also on macOS platform. -- Changes CERN HTCondor compute backend to use the new ``myschedd`` connection library. -- Changes CERN Slurm compute backend to improve job status detection. -- 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) --------------------------- - -- Adds generic job manager class and provides example classes for CERN HTCondor - and CERN Slurm clusters. -- Moves job controller to the same Kubernetes pod with the - REANA-Workflow-Engine-* (sidecar pattern). -- Adds sidecar container to the Kubernetes job pod if Kerberos authentication - is required. -- Provides user secrets to the job container runtime tasks. -- Refactors job monitoring using singleton pattern. - -Version 0.5.1 (2019-04-23) --------------------------- - -- Pins ``urllib3`` due to a conflict while installing ``Kubernetes`` Python - library. -- Fixes documenation build badge. - -Version 0.5.0 (2019-04-23) --------------------------- - -- Adds a new endpoint to delete jobs (Kubernetes). -- Introduces new common interface for job management which defines what the - compute backends should offer to be compatible with REANA, currently only - Kubernetes backend is supported. -- Fixes security vulnerability which allowed users to access other people's - workspaces. -- Makes CVMFS mounts optional and configurable at repository level. -- Updates the creation of CVMFS volumes specification, it now uses normal - persistent volume claims. -- Increases stability and improves test coverage. - -Version 0.4.0 (2018-11-06) --------------------------- - -- Improves REST API documentation rendering. -- Changes license to MIT. - -Version 0.3.2 (2018-09-26) --------------------------- - -- Adapts Kubernetes API adaptor to mount shared volumes on jobs as CEPH - ``persistentVolumeClaim``'s (managed by ``reana-cluster``) instead of plain - CEPH volumes. - -Version 0.3.1 (2018-09-07) --------------------------- - -- Pins REANA-Commons and REANA-DB dependencies. - -Version 0.3.0 (2018-08-10) --------------------------- - -- Adds uwsgi for production deployments. -- Switches from pykube to official Kubernetes python client. -- Adds compatibility with latest Kubernetes. - - -Version 0.2.0 (2018-04-19) --------------------------- - -- Adds dockerignore file to ease developments. - -Version 0.1.0 (2018-01-30) --------------------------- - -- Initial public release. - -.. admonition:: Please beware - - Please note that REANA is in an early alpha stage of its development. The - developer preview releases are meant for early adopters and testers. Please - don't rely on released versions for any production purposes yet. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.md similarity index 74% rename from CONTRIBUTING.rst rename to CONTRIBUTING.md index d6f2944f..dd2c670c 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-job-controller/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 b0ecbe3b..1c5a1d02 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -7,7 +7,6 @@ include *.in include *.json include *.md -include *.rst include *.sh include *.txt include *.yaml @@ -23,7 +22,7 @@ prune docs/_build recursive-include reana_job_controller *.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 recursive-include etc *.conf diff --git a/README.md b/README.md new file mode 100644 index 00000000..fea3d2df --- /dev/null +++ b/README.md @@ -0,0 +1,35 @@ +# REANA-Job-Controller + +[![image](https://github.com/reanahub/reana-job-controller/workflows/CI/badge.svg)](https://github.com/reanahub/reana-job-controller/actions) +[![image](https://readthedocs.org/projects/reana-job-controller/badge/?version=latest)](https://reana-job-controller.readthedocs.io/en/latest/?badge=latest) +[![image](https://codecov.io/gh/reanahub/reana-job-controller/branch/master/graph/badge.svg)](https://codecov.io/gh/reanahub/reana-job-controller) +[![image](https://img.shields.io/badge/discourse-forum-blue.svg)](https://forum.reana.io) +[![image](https://img.shields.io/github/license/reanahub/reana-job-controller.svg)](https://github.com/reanahub/reana-job-controller/blob/master/LICENSE) +[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) + +## About + +REANA-Job-Controller is a component of the [REANA](http://www.reana.io/) reusable and +reproducible research data analysis platform. It takes care of executing and managing +jobs on compute clouds. + +## Features + +- submit jobs to compute clouds +- enquire about status of running jobs + +## 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-Job-Controller releases](https://reana-job-controller.readthedocs.io/en/latest#changes) +- [REANA-Job-Controller docker images](https://hub.docker.com/r/reanahub/reana-job-controller) +- [REANA-Job-Controller developer documentation](https://reana-job-controller.readthedocs.io/) +- [REANA-Job-Controller known issues](https://github.com/reanahub/reana-job-controller/issues) +- [REANA-Job-Controller source code](https://github.com/reanahub/reana-job-controller) diff --git a/README.rst b/README.rst deleted file mode 100644 index a21b098b..00000000 --- a/README.rst +++ /dev/null @@ -1,53 +0,0 @@ -#################### -REANA-Job-Controller -#################### - -.. image:: https://github.com/reanahub/reana-job-controller/workflows/CI/badge.svg - :target: https://github.com/reanahub/reana-job-controller/actions - -.. image:: https://readthedocs.org/projects/reana-job-controller/badge/?version=latest - :target: https://reana-job-controller.readthedocs.io/en/latest/?badge=latest - -.. image:: https://codecov.io/gh/reanahub/reana-job-controller/branch/master/graph/badge.svg - :target: https://codecov.io/gh/reanahub/reana-job-controller - -.. 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-job-controller.svg - :target: https://github.com/reanahub/reana-job-controller/blob/master/LICENSE - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - -About -===== - -REANA-Job-Controller is a component of the `REANA `_ -reusable and reproducible research data analysis platform. It takes care of -executing and managing jobs on compute clouds. - -Features -======== - -- submit jobs to compute clouds -- enquire about status of running jobs - -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-Job-Controller releases `_ -- `REANA-Job-Controller docker images `_ -- `REANA-Job-Controller developer documentation `_ -- `REANA-Job-Controller known issues `_ -- `REANA-Job-Controller source code `_ diff --git a/docs/conf.py b/docs/conf.py index bec2f261..8aa5bbc6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,6 +44,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "myst_parser", "sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.doctest", @@ -76,14 +77,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 = "2017-2023, info@reana.io" +copyright = "2017-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 00000000..0eb64b06 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,107 @@ +```{include} ../README.md +:end-before: "## About" +``` + +```{include} ../README.md +:start-after: "## About" +:end-before: "## Useful links" +``` + +## API + +### Compute backends + +REANA-Job-Controller offers an abstract interface to submit jobs to different +compute backends. + +```{eval-rst} +.. automodule:: reana_job_controller.job_manager + :members: +``` + +```{image} /_static/reana-job-manager.png +``` + +### Kubernetes + +```{eval-rst} +.. automodule:: reana_job_controller.kubernetes_job_manager + :members: +``` + +:::{note} +REANA-Job-Controller supports the Kubernetes job manager by default, no need +to pass any build argument. +::: + +### HTCondor + +```{eval-rst} +.. automodule:: reana_job_controller.htcondorcern_job_manager + :members: +``` + +:::{note} +To build REANA-Job-Controller Docker image with HTCondor dependencies use build +argument `COMPUTE_BACKENDS=kubernetes,htcondorcern`. + +```console +$ reana-dev docker-build -c reana-job-controller \ + -b COMPUTE_BACKENDS=kubernetes,htcondorcern +``` +::: + +### Slurm + +```{eval-rst} +.. automodule:: reana_job_controller.slurmcern_job_manager + :members: +``` + +:::{note} +To build REANA-Job-Controller Docker image with Slum dependencies use build +argument `COMPUTE_BACKENDS=kubernetes,slurmcern`. + +```console +$ reana-dev docker-build -c reana-job-controller \ + -b COMPUTE_BACKENDS=kubernetes,slurmcern +``` +::: + +:::{note} +Please note that CERN Slurm cluster access is not granted by +[default](https://batchdocs.web.cern.ch/linuxhpc/access.html). +::: + +## REST API + +The REANA Job Controller API offers different endpoints to create, manage and monitor jobs. +Detailed REST API documentation can be found here. + +```{eval-rst} +.. automodule:: reana_job_controller.rest + :members: + :exclude-members: JobCreationCondition,get_openapi_spec +``` + +```{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 c835451b..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. include:: ../README.rst - :end-before: About - -.. include:: ../README.rst - :start-after: ===== - :end-before: Features - -Features: - -.. include:: ../README.rst - :start-line: 32 - :end-before: Useful links - -API -=== - -Compute backends ----------------- - -REANA-Job-Controller offers an abstract interface to submit jobs to different -compute backends. - -.. automodule:: reana_job_controller.job_manager - :members: - -.. image:: /_static/reana-job-manager.png - - -Kubernetes -~~~~~~~~~~ - -.. automodule:: reana_job_controller.kubernetes_job_manager - :members: - -.. note:: - REANA-Job-Controller supports the Kubernetes job manager by default, no need - to pass any build argument. - -HTCondor -~~~~~~~~ - -.. automodule:: reana_job_controller.htcondorcern_job_manager - :members: - -.. note:: - To build REANA-Job-Controller Docker image with HTCondor dependencies use build - argument ``COMPUTE_BACKENDS=kubernetes,htcondorcern``. - - .. code-block:: console - - $ reana-dev docker-build -c reana-job-controller \ - -b COMPUTE_BACKENDS=kubernetes,htcondorcern - -Slurm -~~~~~ - -.. automodule:: reana_job_controller.slurmcern_job_manager - :members: - -.. note:: - To build REANA-Job-Controller Docker image with Slum dependencies use build - argument ``COMPUTE_BACKENDS=kubernetes,slurmcern``. - - .. code-block:: console - - $ reana-dev docker-build -c reana-job-controller \ - -b COMPUTE_BACKENDS=kubernetes,slurmcern - -.. note:: - Please note that CERN Slurm cluster access is not granted by - `default `_. - -REST API -======== - -The REANA Job Controller API offers different endpoints to create, manage and monitor jobs. -Detailed REST API documentation can be found `here <_static/api.html>`_. - -.. automodule:: reana_job_controller.rest - :members: - :exclude-members: get_openapi_spec - -.. 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 257f1f19..46ef122f 100644 --- 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", "sphinxcontrib-httpdomain>=1.5.0", @@ -83,6 +84,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-job-controller",