Merge pull request #201 from crim-ca/doc-app-pkg

add docs example references (relates to #61)
crim-ca · Sep 25, 2020 · 5f2bd98 · 5f2bd98
2 parents 2eefabb + c6635d8
commit 5f2bd98
Show file tree

Hide file tree

Showing 9 changed files with 63 additions and 4 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -2,7 +2,9 @@
 version: 2
 sphinx:
   configuration: docs/source/conf.py
-formats: all
+#formats: all
+formats:
+  - htmlzip
 python:
   version: 3.7
   install:

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -9,6 +9,7 @@ Changes
 Changes:
 --------
 - Add ``data`` input support for `CWL` `Workflow` step referring to `WPS-3 Process`.
+- Add documentation example references to `Application Package` and `Process` ``Deploy``/``Execute`` repositories.
 
 Fixes:
 ------

diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,33 @@
+.. _examples-page:
+.. include:: references.rst
+
+********************************************
+Process and Application Package Examples
+********************************************
+
+The principal source of examples can be found directly within |weaver-func-test-apps|_. Most :term:`Process` listed
+in this repository employ an :term:`Application Package` defined using a locally provided :term:`CWL`. Some other
+cases will refer to pre-deployed :term:`WPS` processes. Refer to corresponding |deploy-req-name|_ request payloads,
+also provided in that location, that will indicate the kind of :term:`Process` definition employed through their
+``executionUnit`` specification. Once successfully deployed on a :term:`ADES` or :term:`EMS`, the also provided
+|exec-req-name|_ request body can be employed as format reference to run the operation (input values can be modified).
+
+The general naming convention is:
+
+    - ``DeployProcess_<PROCESS_ID>.json`` for the |deploy-req-name|_ request payload.
+    - ``Execute_<PROCESS_ID>.json`` for the |exec-req-name|_ request payload.
+    - ``<PROCESS_ID>.cwl`` for the :term:`CWL` :term:`Application Package` when applicable.
+
+.. note::
+    There can be minor variations (camel/snake case, upper/lower case) of the exact ``<PROCESS_ID>`` employed in the
+    file names according to the different reference repositories.
+
+
+Further examples are also available following `OGC Testbeds` developments. The produced applications in this case can
+be found in |ogc-testbeds-apps|_. In that repository, the above naming convention will sometime be employed, but each
+:term:`Process` is contained within its own sub-directory. Another naming conversion is sometime used, although the
+files provide equivalent details:
+
+    - ``<PROCESS_ID>/deploy.json`` for the |deploy-req-name|_ request payload.
+    - ``<PROCESS_ID>/execute.json`` for the |exec-req-name|_ request payload.
+    - ``<PROCESS_ID>/package.cwl`` for the :term:`CWL` :term:`Application Package` when applicable.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -121,4 +121,10 @@ continuously improved by the developers (including being updated according to ch
 - |cwl-guide|_
 - |cwl-cmdtool|_
 - |cwl-workflow|_
+- See also below.
 
+
+Where can I find examples of Process Deployment, Execution and Application Package definitions?
+=====================================================================================================
+
+Many examples are reported in detail in the |examples|_ chapter.
diff --git a/docs/source/package.rst b/docs/source/package.rst
@@ -132,7 +132,7 @@ preserve and enforce matching input/output ``format`` definition in both :term:`
 not introduce ambiguous results (see :ref:`File Format` for more details).
 
 
-Correspondance between CWL and WPS fields
+Correspondence between CWL and WPS fields
 ===========================================
 
 Because :term:`CWL` definition and :term:`WPS` process description inherently provide "duplicate" information, many

diff --git a/docs/source/processes.rst b/docs/source/processes.rst
@@ -19,6 +19,11 @@ Each one of them are accessible through the same API interface, but they have di
 - `Remote Provider`_
 
 
+.. seealso::
+    Section |examples|_ provides multiple concrete use cases of `Deploy`_ and `Execute`_ request payloads
+    for diverse set of applications.
+
+
 Builtin
 -------
 

diff --git a/docs/source/references.rst b/docs/source/references.rst
@@ -61,6 +61,14 @@
 .. |submit-issue| replace:: submit a new issue
 .. _submit-issue: https://github.com/crim-ca/weaver/issues/new/choose
 
+.. Example references
+.. |examples| replace:: Examples
+.. _examples: examples.rst
+.. |weaver-func-test-apps| replace:: Weaver functional tests
+.. _weaver-func-test-apps: https://github.com/crim-ca/weaver/tree/master/tests/functional/application-packages
+.. |ogc-testbeds-apps| replace:: OGC-Testbeds Applications
+.. _ogc-testbeds-apps: https://github.com/crim-ca/application-packages
+
 .. External references
 .. _Celery: https://docs.celeryproject.org/en/latest/
 .. _Gunicorn: https://gunicorn.org/
@@ -79,12 +87,17 @@
 .. _email-template: ../../../weaver/wps_restapi/templates/notification_email_example.mako
 
 .. API requests
+.. Full path displayed, otherwise use '-name' suffixed reference for same link with only the general name (no path)
+.. |deploy-req-name| replace:: Deploy
+.. _deploy-req-name: `deploy-req`_
 .. |deploy-req| replace:: ``POST {WEAVER_URL}/processes`` (Deploy)
 .. _deploy-req: https://pavics-weaver.readthedocs.io/en/latest/api.html#tag/Processes%2Fpaths%2F~1processes%2Fpost
 .. |getcap-req| replace:: ``GET {WEAVER_URL}/processes`` (GetCapabilities)
 .. _getcap-req: https://pavics-weaver.readthedocs.io/en/latest/api.html#tag/Processes%2Fpaths%2F~1processes%2Fget
 .. |describe-req| replace:: ``GET {WEAVER_URL}/processes/{id}`` (DescribeProcess)
 .. _describe-req: https://pavics-weaver.readthedocs.io/en/latest/api.html#tag/Processes%2Fpaths%2F~1processes~1%7Bprocess_id%7D~1package%2Fget
+.. |exec-req-name| replace:: Execute
+.. _exec-req-name: `exec-req`_
 .. |exec-req| replace:: ``POST {WEAVER_URL}/processes/{id}/jobs`` (Execute)
 .. _exec-req: https://pavics-weaver.readthedocs.io/en/latest/api.html#tag/Processes%2Fpaths%2F~1processes~1{process_id}~1jobs%2Fpost
 .. |vis-req| replace:: ``PUT {WEAVER_URL}/processes/{id}/visibility`` (Visibility)

diff --git a/docs/source/toc.rst b/docs/source/toc.rst
@@ -12,6 +12,7 @@ Table of Contents
     tutorial
     processes
     package
+    Examples <examples.rst>
     OpenAPI Specification <api.rst>
     Source Code Documentation <autoapi/index.rst>
     changes

diff --git a/weaver/__meta__.py b/weaver/__meta__.py
@@ -2,8 +2,6 @@
 __title__ = "Weaver"
 __version__ = "1.13.1"
 __description__ = "Workflow Execution Management Service (EMS); Application, Deployment and Execution Service (ADES)."
-# __source_repository__ = "https://www.crim.ca/stash/projects/OGC/repos/weaver"
-# __docker_repository__ = "docker-registry.crim.ca/ogc/weaver:latest"
 __source_repository__ = "https://github.com/crim-ca/weaver"
 __docker_repository__ = "https://hub.docker.com/r/pavics/weaver"
 __license_type__ = "Apache License 2.0"