more config setting docs (#61)

docs/source/configuration.rst

@@ -1,4 +1,5 @@
 .. _configuration:
+.. include:: references.rst
 
 ******************
 Configuration
@@ -15,10 +16,114 @@ Configuration Settings
 =======================================
 
 All settings are configured using a ``weaver.ini`` configuration file. A `weaver.ini.example`_ file is provided
-with default values to help in the configuration process.
+with default values to help in the configuration process. Explanations of respective settings are also available in
+this example file.
+
+The configuration file tell the application runner (e.g. `Gunicorn`_, ``pserve`` or similar WSGI HTTP Server), how to
+execute `Weaver` as well as all settings to provide in order to personalize the application. All settings specific to
+`Weaver` employ the format ``weaver.<setting>``.
+
+Following is a partial list of most predominant settings. Note that all following settings should be applied under
+section ``[app:main]`` of `weaver.ini.example`_ for the application to resolve them.
+
+- | ``weaver.configuration = ADES|EMS``
+  |
+  | Tells the application in which mode to run. Enabling `ADES` for instance will disable some `EMS`-specific
+  | operations such as dispatching `Workflow`_ process steps to known remote `ADES` servers.
+
+- | ``weaver.url = <url>``
+  |
+  | Defines the full URL (including HTTP protocol/scheme, hostname and optionally additional path suffix) that will
+  | be used as base URL for all other URL settings of `Weaver`.
+
+.. note::
+
+    This is the URL that you want displayed in responses (e.g.: ``processDescriptionURL`` or job ``location``).
+    For the effective URL employed by the WSGI HTTP server, refer to ``[server:main]`` section of `weaver.ini.example`_.
+
+- | ``weaver.wps = true|false``
+  |
+  | Enables the WPS-1/2 endpoint.
+
+ .. warning::
+
+     At the moment, this setting must be ``true`` to allow job execution as the worker monitors this endpoint.
+     This could change with future developments (see issue `#21 <https://github.com/crim-ca/weaver/issues/21>`_).
+
+- | ``weaver.wps_path = <url-path>``
+  | ``weaver.wps_url = <full-url>``
+  | (default: *path* ``/ows/wps``)
+  |
+  | Defines the URL to employ as WPS-1/2 endpoint.
+  |
+  | It can either be the explicit *full URL* to use or the *path* relative to ``weaver.url``.
+  | Setting ``weaver.wps_path`` is ignored if its URL equivalent is defined.
+  | The *path* variant **SHOULD** start with ``/`` for appropriate concatenation with ``weaver.url``, although this is
+  | not strictly enforced.
+
+- | ``weaver.wps_output_dir = <directory-path>``
+  | (default: ``/tmp``)
+  |
+  | Location where WPS outputs (results from jobs) will be stored for stage-out. This directory should be mapped to
+  | `Weaver`'s WPS output URL to serve them externally as needed.
+
+- | ``weaver.wps_output_path = <url-path>``
+  | ``weaver.wps_output_url = <full-url>``
+  | (default: *path* ``/wpsoutputs``)
+  |
+  | Endpoint that will be employed as prefix to refer to WPS outputs (job results).
+  |
+  | It can either be the explicit *full URL* to use or the *path* relative to ``weaver.url``.
+  | Setting ``weaver.wps_output_path`` is ignored if its URL equivalent is defined.
+  | The *path* variant **SHOULD** start with ``/`` for appropriate concatenation with ``weaver.url``, although this is
+  | not strictly enforced.
+
+- | ``weaver.wps_workdir = <directory-path>``
+  | (default: uses automatically generated temporary directory if none specified)
+  |
+  | Prefix where process job worker should execute the process from.
+
+- | ``weaver.wps_restapi = true|false``
+  | (default: ``true``)
+  |
+  | Enable the WPS-REST endpoint.
+
+.. note::
+
+    `Weaver` looses most, if not all, of its useful features without this, and there won't be much point in using
+    it without REST endpoint, but it should technically be possible to run it as WPS-1/2 only if desired.
+
+- | ``weaver.wps_restapi_path = <url-path>``
+  | ``weaver.wps_restapi_url = <full-url>``
+  | (default: *path* ``/``)
+  |
+  | Endpoint that will be employed as prefix to refer to WPS-REST requests
+  | (including but not limited to |ogc-proc-api|_ schemas).
+  |
+  | It can either be the explicit *full URL* to use or the *path* relative to ``weaver.url``.
+  | Setting ``weaver.wps_restapi_path`` is ignored if its URL equivalent is defined.
+  | The *path* variant **SHOULD** start with ``/`` for appropriate concatenation with ``weaver.url``, although this is
+  | not strictly enforced.
+
+- | ``weaver.wps_metadata_[...]`` settings group
+  |
+  | Metadata fields that will be rendered by either or both the WPS-1/2 and WPS-REST endpoints (`GetCapabilities`_).
+
+- | ``weaver.wps_email_[...]`` settings group
+  |
+  | Defines configuration email notification functionality on job completion.
+  |
+  | Encryption settings as well as custom email templates are available. Email notifications are sent only on job
+  | completion if an email was provided in the `Execute`_ request body.
+
+.. seealso::
+    - `Execute`_ request details.
 
-.. todo:: complete docs
 
+.. note::
+
+    Refer to `weaver.ini.example`_ for the extended list of applicable settings.
+    Some advanced configuration settings are also described in the below sections.
 
 
 Configuration of Data Sources
@@ -59,13 +164,16 @@ To disable this feature and avoid any auto-deployment provided by this functiona
 Configuration of Request Options
 =======================================
 
-.. versionadded:: 1.8.0
-
 .. todo:: complete docs
 
+``weaver.ssl_verify``
+
+
+.. versionadded:: 1.8.0
 
 `request_options.yml.example`_
 
+
 Starting the Application
 =======================================
 
@@ -76,12 +184,3 @@ Starting the Application
 - need to start ``gunicorn/pserve`` (example `Dockerfile-manager`_)
 - need to start ``celery`` worker (example `Dockerfile-worker`_)
 
-
-.. _weaver.config: ../../../config
-.. _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
-

docs/source/processes.rst

@@ -244,6 +244,14 @@ Execution of a process (Execute, Job)
 
 .. todo::
 
+
+
+When a job is executed by specifying the ``notification_email`` field, the resulting process execution will send an
+email to the specified address with successful or failure details. The format of the email is configurable from
+`weaver.ini.example`_ file
+
+.. _exec-req: https://pavics-weaver.readthedocs.io/en/latest/api.html#tag/Processes%2Fpaths%2F~1processes~1{process_id}~1jobs%2Fpost
+
 .. _GetStatus:
 
 Monitoring of a process (GetStatus)

docs/source/references.rst

@@ -24,3 +24,14 @@
 .. _ogc-home: `ogc`_
 .. |ogc-proc-api| replace:: OGC API - Processes
 .. _ogc-proc-api: https://github.com/opengeospatial/wps-rest-binding
+
+.. _Gunicorn: http://gunicorn.org/
+.. _MongoDB: https://www.mongodb.com/
+
+.. _weaver.config: ../../../config
+.. _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

docs/source/running.rst

@@ -1,4 +1,5 @@
 .. _running:
+.. include:: references.rst
 
 ****************
 Running Weaver
@@ -29,8 +30,6 @@ It will be available under the configured URL endpoint in ``weaver/config/weaver
 If everything was configured correctly, calling this URL (default: ``http://localhost:4001``) should
 provide a response containing a JSON body with basic information about Weaver.
 
-.. _Gunicorn: http://gunicorn.org/
-.. _MongoDB: https://www.mongodb.com/
 
 Using WPS Application
 =====================