add sections for docs (#61)

crim-ca · Jun 4, 2020 · 6958ece · 6958ece
1 parent a1f8e58
commit 6958ece
Show file tree

Hide file tree

Showing 12 changed files with 167 additions and 31 deletions.
diff --git a/.codacy.yml b/.codacy.yml
@@ -1,4 +1,4 @@
 ---
 exclude_paths:
   - 'tests/**'
-  - 'docs/conf.py'
+  - 'docs/source/conf.py'
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,7 +1,7 @@
 # configuration to setup readthedocs
 version: 2
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/source/conf.py
 formats: all
 python:
   version: 3.7

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -9,6 +9,7 @@ Changes
 Changes:
 --------
 - Generate Weaver OpenAPI specification for readthedocs publication.
+- Add some sections for documentation (`#61 <https://github.com/crim-ca/weaver/issues/61>`_).
 
 Fixes:
 ------

diff --git a/README.rst b/README.rst
@@ -97,7 +97,7 @@ For more details, see `Configuration`_ and `Documentation`_ sections.
 Links
 ----------------
 
-Docker image repositories: 
+Docker image repositories:
 
 - CRIM registry: `ogc/weaver <https://docker-registry.crim.ca/repositories/3463>`_
 - OGC processes: `ogc-public <https://docker-registry.crim.ca/namespaces/39>`_
@@ -140,13 +140,15 @@ For more configuration details, please refer to Documentation_.
 Documentation
 ----------------
 
-The REST API documentation is auto-generated and served under ``{WEAVER_URL}/api/`` using
-Swagger-UI with tag ``latest``.
+The REST API documentation is auto-generated and served under any running `Weaver` application on route
+``{WEAVER_URL}/api/``. This documentation will correspond to the version of the executed `Weaver` application.
+For the latest documentation, you can refer to the `OpenAPI Specification <rtd_oas>`_ served directly on `readthedocs`_.
 
-More ample details about installation, configuration and usage are provided on `readthedocs`_.
-These are generated from corresponding information provided in `docs`_.
+More ample details about installation, configuration and usage are also provided on `readthedocs`_.
+These are generated from corresponding information provided in `docs`_ source directory.
 
 .. _readthedocs: https://pavics-weaver.readthedocs.io
+.. _rtd_oas: https://pavics-weaver.readthedocs.io/en/latest/api.html
 .. _docs: ./docs
 
 ----------------

diff --git a/docs/Makefile b/docs/Makefile
@@ -1,8 +1,5 @@
 # Makefile for Sphinx documentation
 #
-MAKEFILE_NAME := $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST))
--include Makefile.config	# Include custom config if it is available
-CUR_DIR := $(abspath $(lastword $(MAKEFILE_NAME))/..)
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
@@ -13,9 +10,9 @@ BUILDDIR      = build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -c $(CUR_DIR)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -c $(CUR_DIR)
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

diff --git a/docs/conf.py → docs/source/conf.py b/docs/conf.py → docs/source/conf.py
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -37,6 +37,13 @@ Configuration of WPS Processes
 
 `wps_processes.yml.example`_
 
+Configuration of Request Options
+=======================================
+
+.. todo:: complete docs
+
+
+`request_options.yml.example`_
 
 Starting the Application
 =======================================
@@ -53,5 +60,6 @@ Starting the Application
 .. _weaver.ini.example: ../../../config/weaver.ini.example
 .. _data_sources.json.example: ../../../config/data_sources.json.example
 .. _wps_processes.yml.example: ../../../config/wps_processes.yml.example
+.. _request_options.yml.example: ../../../config/request_options.yml.example
 .. _Dockerfile-manager: ../../../docker/Dockerfile-manager
 .. _Dockerfile-worker: ../../../docker/Dockerfile-worker
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,5 +7,7 @@
    configuration
    running
    tutorial
+   processes
+   package
    changes
    appendix
diff --git a/docs/source/package.rst b/docs/source/package.rst
@@ -0,0 +1,53 @@
+.. package
+
+*************************
+Application Package (CWL)
+*************************
+
+.. todo:: demo docs
+
+Based on `Common Workflow Language <CWL>`_ (CWL) `specification <cwl-spec>`_.
+
+
+
+.. _CWL: https://www.commonwl.org/
+.. _cwl_spec: https://www.commonwl.org/#Specification
+
+
+Typical CWL Package Definition
+===========================================
+
+.. todo:: CommandLineTool
+
+Correspondance between CWL and WPS fields
+===========================================
+
+.. todo:: demo docs
+
+
+Correspondance between CWL and WPS fields
+===========================================
+
+Input / Outputs
+-----------------------
+
+.. todo:: mapping with 'id'
+.. todo:: CWL Lit. <-> WPS Literal
+.. todo:: CWL File <-> WPS Complex
+
+File Format
+-----------------------
+
+.. todo:: demo docs
+
+Allowed Values
+-----------------------
+
+
+.. todo:: cwl enum vs allowed/supported WPS
+
+
+Multiple Values
+-----------------------
+
+.. todo:: minOccurs/maxOccurs + array + WPS repeats IDs vs CWL as list
diff --git a/docs/source/processes.rst b/docs/source/processes.rst
@@ -0,0 +1,66 @@
+.. _processes:
+
+**********
+Processes
+**********
+
+Type of Processes
+=====================
+
+- Builtin
+- WPS-1/2
+- WPS-3 (WPS-REST)
+- ESGF-CWT
+- Workflow
+- Remote Provider
+
+
+
+
+Managing processes included in Weaver ADES/EMS
+==================================================
+
+Following steps represent the typical steps applied to deploy a process, execute it and retrieve the results.
+
+Register a new process (Deploy)
+-----------------------------------------
+
+.. todo:: complete demo docs
+
+
+Access registered process(es) (GetCapabilities, DescribeProcess)
+------------------------------------------------------------------------
+
+.. todo:: complete demo docs, stuff about process visibility
+
+
+Execution of a process (Execute, Job)
+---------------------------------------------------------------------
+
+.. todo::
+
+Monitoring of a process (GetStatus)
+---------------------------------------------------------------------
+
+.. todo::
+
+Obtaining output results, logs or errors  (GetStatus)
+---------------------------------------------------------------------
+
+.. todo::
+
+
+
+Special Weaver EMS use-cases
+==================================================
+
+OpenSearch data source
+--------------------------------------
+
+.. todo:: EOImage with AOI/TOI/CollectionId for OpenSearch
+
+Workflow (Chaining Step Processes)
+--------------------------------------
+
+.. todo:: reference IDs of steps
+
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
@@ -12,15 +12,26 @@ Tutorial
 Using the WPS application included in Weaver
 ==============================================
 
-Install Weaver (see: :ref:`installation`) and make sure all required components
+Install `Weaver` (see: :ref:`installation`) and make sure all required components
 are started and running (see: :ref:`configuration`).
 
-Then, execute the desired `WPS`_ request according to desired operation mode and version.
+Then, execute the desired `WPS`_ or `WPS-REST`_ request according to desired operation mode and version.
 
 For all following examples, ``${WEAVER_URL}`` is used to specify your application URL endpoint configuration.
 By default, this value should be ``localhost:4001``.
 
-.. _`WPS`: https://www.opengeospatial.org/standards/wps
+.. _WPS: https://www.opengeospatial.org/standards/wps
+.. _WPS-REST: https://github.com/opengeospatial/wps-rest-binding
+
+.. note::
+    This tutorial section is a minimal introduction to available requests and endpoints. Please refer to
+    `processes`_ for further details, such as detailed request payload contents, types of processes and additional
+    operations that compose a typical process execution workflow. Similarly, refer to
+    `Application Package <package>`_ for further details about the definition of the reference application executed
+    by the deployed processes.
+
+.. _processes: ./processes.rst
+.. _package: ./package.rst
 
 WPS-1/2 requests
 --------------------
@@ -61,6 +72,10 @@ Then, run the WPS-1/WPS-2 ``Execute`` request (built-in process ``jsonarray2netc
 The execution of the process should read the JSON list with our dummy NetCDF file and make it available (as a copy)
 on the output parameter named ``output`` with a path matching the configured output WPS path of the application.
 
+.. note::
+    All above WPS-1/2 requests suppose that configuration setting ``weaver.wps_path /ows/wps`` (default value).
+    The request URL have to be adjusted accordingly if this parameter is modified.
+
 WPS-3 requests
 --------------
 
@@ -101,19 +116,11 @@ For all available operations and specific details about them, please refer to th
 rendered on route ``${WEAVER_URL}/api`` when running `Weaver` application.
 
 
-Managing WPS processes included in Weaver ADES/EMS
-==================================================
-
-Register a new WPS process
---------------------------
-
-.. todo:: complete demo docs
-
-
-Access a registered process
----------------------------
-
-.. todo:: complete demo docs, stuff about process visibility
-
-
+Endpoint Content-Type
+------------------------
 
+.. todo:: wps-1/2 xml default, json supported wps-2
+.. todo::
+    wps-rest json only (for now, xml also if implemented)
+    https://github.com/crim-ca/weaver/issues/125
+    https://github.com/crim-ca/weaver/issues/126
diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -1,6 +1,6 @@
 # these are doc-only requirements
 # we actually need to install all requirements during docs build because of OpenAPI generation
-# (see 'docs/conf.py')
+# (see 'docs/source/conf.py')
 pycodestyle
 pycodestyle
 # required for pywps.ext_autodoc