docs: single-page RTFD outline

* Addresses reanahub/reana#335.
reanahub · Jul 29, 2020 · 1cb473b · 1cb473b
1 parent 069fbb3
commit 1cb473b
Show file tree

Hide file tree

Showing 15 changed files with 119 additions and 169 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,10 +1,7 @@
 Contributing
 ============
 
-Issues
-------
-
-Bug reports, feature requests, and other contributions are welcome. If you find
+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
@@ -13,21 +10,11 @@ a demonstrable problem that is caused by the REANA code, please:
    latest `master` branch.
 3. Create an issue, ideally with **a test case**.
 
-Pull requests
--------------
-
-If you create a feature branch, you can run the tests to ensure that everything
-is operating correctly:
+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
 
 Each pull request should preserve or increase code coverage.
-
-Kanban
-------
-
-We are using Kanban technique for keeping track of ongoing tasks. Please see
-our `Kanban boards <https://github.com/orgs/reanahub/projects>`_ and look for
-issues that are "ready for work".
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (C) 2017, 2018 CERN.
+Copyright (C) 2017-2020 CERN.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

diff --git a/README.rst b/README.rst
@@ -1,6 +1,6 @@
-======================
- REANA-Job-Controller
-======================
+####################
+REANA-Job-Controller
+####################
 
 .. image:: https://img.shields.io/travis/reanahub/reana-job-controller.svg
    :target: https://travis-ci.org/reanahub/reana-job-controller
@@ -21,26 +21,33 @@
    :target: 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
-------------
+============
 
-- `documentation <https://reana-job-controller.readthedocs.io/>`_
-- `releases <https://github.com/reanahub/reana-job-controller/releases>`_
-- `known issues <https://github.com/reanahub/reana-job-controller/issues>`_
-- `source code <https://github.com/reanahub/reana-job-controller>`_
+- `REANA project home page <http://www.reana.io/>`_
+- `REANA user documentation <https://docs.reana.io>`_
+- `REANA user support forum <https://forum.reana.io>`_
 
-For more information about the REANA reusable analysis platform, please see the
-`REANA project <http://www.reana.io>`_ home page and the general `REANA
-documentation <http://reana.readthedocs.io/>`_ pages.
+- `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/docs/_static/logo-reana.png b/docs/_static/logo-reana.png
diff --git a/docs/authors.rst b/docs/authors.rst
diff --git a/docs/changes.rst b/docs/changes.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -77,7 +77,7 @@
 
 # General information about the project.
 project = "reana"
-copyright = "2017-2019, info@reana.io"
+copyright = "2017-2020, info@reana.io"
 author = "info@reana.io"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -126,7 +126,6 @@
 # documentation.
 #
 html_theme_options = {
-    "logo": "logo-reana.png",
     "description": """<p>REANA-Job-Controller is a component of the <a
                       href="http://www.reana.io">REANA</a> reusable and
                       reproducible research data analysis
@@ -143,12 +142,13 @@
         "REANA@Twitter": "https://twitter.com/reanahub",
         "REANA@Web": "http://www.reana.io",
     },
+    "nosidebar": True,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {

diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/developerguide.rst b/docs/developerguide.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,16 +2,96 @@
    :end-before: About
 
 .. include:: ../README.rst
-   :start-after: -----
+   :start-after: =====
    :end-before: Features
 
-.. toctree::
-   :numbered:
+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 <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 <_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
 
-   introduction
-   restapi
-   developerguide
-   contributing
-   changes
-   license
-   authors
diff --git a/docs/introduction.rst b/docs/introduction.rst
diff --git a/docs/license.rst b/docs/license.rst
diff --git a/docs/restapi.rst b/docs/restapi.rst
diff --git a/reana_job_controller/kubernetes_job_manager.py b/reana_job_controller/kubernetes_job_manager.py
@@ -146,7 +146,6 @@ def execute(self):
         secret_env_vars = secrets_store.get_env_secrets_as_k8s_spec()
         job_spec = self.job["spec"]["template"]["spec"]
         job_spec["containers"][0]["env"].extend(secret_env_vars)
-
         job_spec["volumes"].append(secrets_store.get_file_secrets_volume_as_k8s_specs())
 
         secrets_volume_mount = secrets_store.get_secrets_volume_mount_as_k8s_spec()

diff --git a/setup.py b/setup.py
@@ -25,10 +25,10 @@
 extras_require = {
     "debug": ["wdb", "ipdb", "Flask-DebugToolbar",],
     "docs": [
-        "Sphinx>=1.4.4,<1.6",
+        "Sphinx>=1.5.1,<1.6",
         "sphinx-rtd-theme>=0.1.9",
         "sphinxcontrib-httpdomain>=1.5.0",
-        "sphinxcontrib-openapi>=0.3.0",
+        "sphinxcontrib-openapi>=0.3.0,<0.4.0",
         "sphinxcontrib-redoc>=1.5.1",
     ],
     "tests": tests_require,