diff --git a/.codacy.yml b/.codacy.yml index a772a1bf1..ae678bab3 100644 --- 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 index fd0492b54..f1ca28b64 100644 --- 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 index bc4b4d7a6..3cdd792f8 100644 --- 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 `_). Fixes: ------ diff --git a/README.rst b/README.rst index b2e417f90..e453fae4e 100644 --- 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 `_ - OGC processes: `ogc-public `_ @@ -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 `_ 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 index c32f8e9d0..6ec261442 100644 --- 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 b/docs/source/conf.py similarity index 100% rename from docs/conf.py rename to docs/source/conf.py diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index e7bd58e97..b21c56904 100644 --- 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 index 9781cc40a..fd877ff58 100644 --- 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 new file mode 100644 index 000000000..7a739a6ad --- /dev/null +++ b/docs/source/package.rst @@ -0,0 +1,53 @@ +.. package + +************************* +Application Package (CWL) +************************* + +.. todo:: demo docs + +Based on `Common Workflow Language `_ (CWL) `specification `_. + + + +.. _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 new file mode 100644 index 000000000..3d4ce2f08 --- /dev/null +++ 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 index 8e27d9896..dab39f626 100644 --- 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 `_ 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 index bcd62e8e4..73e3c6c94 100644 --- 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