[SDC-DIST-CLIENT] Add new RTD entry

Update README etc

Signed-off-by: efiacor <fiachra.corcoran@est.tech>
Change-Id: I4f92684e82d3fc2df978af12100be0871b94178d
Issue-ID: DMAAP-1792

12 files changed, 506 insertions, 23 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 5371015..80888b3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,15 +1,58 @@
-from docs_conf.conf import *
+project = "onap"
+release = "master"
+version = "master"
 
-branch = 'latest'
-master_doc = 'index'
+author = "Open Network Automation Platform"
+# yamllint disable-line rule:line-length
+copyright = "ONAP. Licensed under Creative Commons Attribution 4.0 International License"
 
-linkcheck_ignore = [
-    'http://localhost',
+pygments_style = "sphinx"
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+  "style_nav_header_background": "white",
+  "sticky_navigation": "False" }
+html_logo = "_static/logo_onap_2017.png"
+html_favicon = "_static/favicon.ico"
+html_static_path = ["_static"]
+html_show_sphinx = False
+
+extensions = [
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.graphviz',
+    'sphinxcontrib.blockdiag',
+    'sphinxcontrib.seqdiag',
+    'sphinxcontrib.swaggerdoc',
+    'sphinxcontrib.plantuml'
 ]
 
+exclude_patterns = ['archived/*.rst', '.tox']
+#
+# Map to 'latest' if this file is used in 'latest' (master) 'doc' branch.
+# Change to {releasename} after you have created the new 'doc' branch.
+#
+
+branch = 'latest'
+
 intersphinx_mapping = {}
+doc_url = 'https://docs.onap.org/projects'
+master_doc = 'index'
+
+spelling_word_list_filename='spelling_wordlist.txt'
+spelling_lang = "en_GB"
+
+#
+# Example:
+# intersphinx_mapping['onap-aai-aai-common'] = ('{}/onap-aai-aai-common/en/%s'.format(doc_url) % branch, None)
+#
 
 html_last_updated_fmt = '%d-%b-%y %H:%M'
 
+
 def setup(app):
-    app.add_stylesheet("css/ribbon.css")
+    app.add_css_file("css/ribbon.css")
+
+
+linkcheck_ignore = [
+  r'http://localhost:\d+/',
+  r'https:\/\/mvnrepository.com\/.*'
+]
\ No newline at end of file
diff --git a/docs/images/sdc_client_init.png b/docs/images/sdc_client_init.png
new file mode 100644
index 0000000..de73f57
--- /dev/null
+++ b/docs/images/sdc_client_init.png
diff --git a/docs/images/sdc_distrib_flow.png b/docs/images/sdc_distrib_flow.png
new file mode 100644
index 0000000..f8a5165
--- /dev/null
+++ b/docs/images/sdc_distrib_flow.png
diff --git a/docs/index.rst b/docs/index.rst
index d567787..01cf3cf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,9 +1,23 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
 .. _master_index:
 
-TODO Add files to toctree and delete this header
-------------------------------------------------
+SDC Distribution Client
+=======================
+
+.. Add or remove sections below as appropriate for the SDK
+
 .. toctree::
    :maxdepth: 1
 
+   ../sections/architecture.rst
+   ../sections/offeredapis.rst
+   ../sections/configuration.rst
+   ../sections/delivery.rst
+   ../sections/build.rst
+   ../sections/release-notes.rst
+
+
 
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 3b3441a..71df2ab 100644
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -1,3 +1,7 @@
-lfdocs-conf
 sphinx>=4.2.0  # BSD
 sphinx-rtd-theme>=1.0.0  # MIT
+sphinxcontrib-blockdiag  # BSD
+sphinxcontrib-seqdiag # BSD
+sphinxcontrib-swaggerdoc
+sphinxcontrib-spelling
+sphinxcontrib-plantuml
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644
index 0000000..a04626d
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,97 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+Architecture
+============
+
+..
+   * This section is used to describe a software component from a high level
+     view of capability, common usage scenarios, and interactions with other
+     components required in the usage scenarios.
+
+   * The architecture section is typically: provided in a platform-component
+     and sdk collections; and referenced from developer and user guides.
+
+   * This note must be removed after content has been added.
+
+
+Capabilities
+------------
+
+The SDC Distribution client is a library that applications can use to simplify the handling of
+distribution related notifications from/to SDC and to download artifacts from SDC based on those notification.
+
+.. note::
+
+    As of version 2.0.0, the client uses kafka as it's message bus to publish/subscribe to/from the
+    relevant SDC distribution topics.
+
+    All previous releases of the client use DMaaP Message Router as it's message bus.
+
+Usage Scenarios
+---------------
+- **Get Distribution Notification event**
+
+    The client polls the relevant NOTIFICATION topic for distribution events sent from SDC.
+
+- **Get Deployment Artifact from SDC**
+
+    Once a new notification event is received, the client will download the relevant artifacts that it
+    has defined as part of it configuration.
+
+- **Send Distribution Status event**
+
+    As part of the processing of the downloaded artifacts, the client will publish it's progress to SDC
+    via the relevant STATUS topic.
+    Once the download has ben successfully completed, the client must publish it's final response
+    COMPONENT_DONE_OK to the STATUS topic.
+
+
+Interactions
+------------
+
+Kafka
+^^^^^
+The client uses kafka as it's messaging bus to publish and subscribe to the relevant SDC topics.
+
+.. _SDCE-6 Swagger api: https://docs.onap.org/projects/onap-sdc/en/latest/_downloads/4eca2a3848d70e58566570a5ef889efb/swagger-sdce-6.json
+.. _SDCE-7 Swagger api: https://docs.onap.org/projects/onap-sdc/en/latest/_downloads/542e76906472dae2e00adfad5fc7d879/swagger-sdce-7.json
+
+SDC
+^^^
+**The client interacts with the following SDC apis on initialization:**
+
+- ``/sdc/v1/artifactTypes``
+
+    Get the current artifact types from SDC to validate against the clients configured list.
+
+    See `SDCE-6 Swagger api`_ for more details
+
+- ``/sdc/v1/distributionKafkaData``
+
+    Get the kafka distribution config from SDC to be used during publish and subscribe
+
+    See `SDCE-6 Swagger api`_ for more details
+
+.. image:: ../images/sdc_client_init.png
+
+
+
+
+**The client interacts with the following SDC apis during distribution:**
+
+- ``/sdc/v1/catalog/services/{serviceName}/{serviceVersion}/resourceInstances/{resourceInstanceName}/artifacts/{artifactName}``
+
+    Get the artifact for a particular resource instance defined in the artifactUrl of the notification event
+
+    See `SDCE-7 Swagger api`_ for more details
+
+- ``/sdc/v1/catalog/services/{serviceName}/{serviceVersion}/artifacts/{artifactName}``
+
+    Get the artifact defined in the artifactUrl of the notification event
+
+    See `SDCE-7 Swagger api`_ for more details
+
+
+.. image:: ../images/sdc_distrib_flow.png
diff --git a/docs/sections/build.rst b/docs/sections/build.rst
new file mode 100644
index 0000000..4ef3e71
--- /dev/null
+++ b/docs/sections/build.rst
@@ -0,0 +1,43 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _build:
+
+Build
+=====
+
+..
+  * This section is used to describe how a software component is built from
+    source into something ready for use either in a run-time environment or to
+    build other components.
+
+  * This section is typically provided for a platform-component, application,
+    and sdk; and referenced in developer guides.
+
+
+Environment
+-----------
+
+- JDK 11
+
+- Maven 3.6.*
+
+  - local .m2 settings.xml set to https://git.onap.org/oparent/plain/settings.xml
+
+For more information regarding Env set up see `Setting Up Your Development Environment`_.
+
+.. _Setting Up Your Development Environment: https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment
+
+
+.. _Build steps:
+
+Steps
+-----
+
+Run the following from project root:
+
+``mvn clean install``
+
+The result is JAR file under the ``sdc-distribution-client/target`` folder
+
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644
index 0000000..964d771
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,126 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _config:
+
+Configuration
+=============
+
+The sdc-distribution-client configuration in ONAP is generally done via a config file
+loaded to the container.
+
+Pre-requisites
+--------------
+The parent project must provide a mechanism to load the configuration at runtime.
+
+This configuration is then passed as input to the parent projects implementation of the
+sdc-distribution-client's IConfiguration interface.
+
+For more detailed information regarding the abstract methods of the interface that must be
+overridden byt the parent project, please refer to the javadocs.
+
+Client configuration
+--------------------
+The table below shows a brief outline of the client config.
+
+.. note::
+    Attention should be given to any methods which provide default values.
+
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| Name                      | Description                                                   | Type    | Required | Default |
++===========================+===============================================================+=========+==========+=========+
+| sdcAddress                | SDC Distribution Engine address                               | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| user                      | User Name for SDC distribution consumer authentication        | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| password                  | User Password for SDC distribution consumer authentication    | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| environmentName           | The environment name. Must match what is set in SDC           | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| useHttpsWithSdc           | Whether to use https towards SDC                              | boolean | N        | true    |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| keyStorePath              | Y If useHttpsWithSdc is true                                  | String  | See desc | NA      |
+|                           | N if activateServerTLSAuth set to false                       |         |          |         |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| keyStorePassword          | Y If useHttpsWithSdc is true                                  | String  | See desc | NA      |
+|                           | N if activateServerTLSAuth set to false                       |         |          |         |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| activateServerTLSAuth     | mTLS setting.                                                 | boolean | Y        | NA      |
+|                           | If false, KeyStore path and password must be set              |         |          |         |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| consumeProduceStatusTopic | Whether to consume from both SDC distribution topics          | boolean | N        | false   |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| consumerGroup             | Group Id to use when consuming from the NOTIFICATION topic    | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| consumerId                | Consumer Id to use when consuming from the NOTIFICATION topic | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| pollingInterval           | Interval between polls on the NOTIFICATION topic in sec       | int     | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| pollingTimeout            | NOTIFICATION topic polling timeout in sec                     | int     | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| relevantArtifactTypes     | List of artifact types the client should consume              | String  | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| filterEmptyResource       | See IConfiguration interface javadoc for more detail          | boolean | Y        | NA      |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| useSystemProxy            | Whether to use system or config proxies towards SDC           | boolean | N        | false   |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpsProxyHost            | The https proxy host to use towards SDC                       | String  | N        | null    |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpsProxyPort            | The https proxy port to use towards SDC                       | int     | N        | 0       |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpProxyHost             | The http proxy host to use towards SDC                        | String  | N        | null    |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+| httpProxyPort             | The http proxy port to use towards SDC                        | int     | N        | 0       |
++---------------------------+---------------------------------------------------------------+---------+----------+---------+
+
+
+Client Kafka config
+^^^^^^^^^^^^^^^^^^^
+
+The client will use kafka as a messaging bus to publish and subscribe to the relevant SDC topics.
+
+The client's kafka configuration in ONAP should be handled via Strimzi kafka's
+KafkaUser custom resource definition which provides access control to the relevant kafka topics.
+
+This is done at helm chart level for each component that requires access to kafka topics.
+
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+| Name                  | Description                                                   | Type   | Required | Default                                      |
++=======================+===============================================================+========+==========+==============================================+
+| kafkaSecurityProtocol | The kafka security.protocol to use towards the kafka endpoint | String | N        | SASL_PLAINTEXT                               |
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+| kafkaSaslMechanism    | The kafka sasl.mechanism to use towards the kafka endpoint    | String | N        | SCRAM-SHA-512                                |
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+| KafkaSaslJaasConfig   | The kafka sasl.jaas.config to use towards the kafka endpoint  | String | Y        | Environment variable set to SASL_JAAS_CONFIG |
++-----------------------+---------------------------------------------------------------+--------+----------+----------------------------------------------+
+
+.. note::
+    The sasl.jaas.config for the client to use will default to an environment variable set as SASL_JAAS_CONFIG.
+
+    This is expected to be in the form of org.apache.kafka.common.security.scram.ScramLoginModule required username="user" password="password";
+
+
+Initializing the client
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Once the client config is loaded, it can then be passed to the IDistributionClient to initialize.
+
+..  code-block:: java
+
+    // CustomClientConfig implementing IConfiguration
+    CustomClientConfig config = loadClientConfig();
+
+    IDistributionClient client = DistributionClientFactory.createDistributionClient();
+
+    // MyNotificationCallback implementing INotificationCallback
+    MyNotificationCallback callback;
+
+    IDistributionClientResult result = client.init(config, callback);
+    //Verify the result is SUCCESS, otherwise there’s a problem setting up vs either SDC or Kafka clients
+    System.out.println(result.getDistributionMessageResult());
+
+    System.out.println("Starting client...");
+    IDistributionClientResult startResult = client.start();
+    // Verify the result is SUCCESS, otherwise there’s a problem in receiving/sending notifications to/from kafka topics
+    System.out.println(startResult.getDistributionMessageResult());
diff --git a/docs/sections/delivery.rst b/docs/sections/delivery.rst
new file mode 100644
index 0000000..135dcd3
--- /dev/null
+++ b/docs/sections/delivery.rst
@@ -0,0 +1,23 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+Delivery
+========
+
+..
+   * This section is used to describe the delivery of a software component.
+     For a run-time component, this might be executable images, containers, etc.
+     For an SDK, this might be libraries.
+
+   * This section is typically provided for a platform-component and sdk;
+     and referenced in developer and user guides.
+
+Deliverables
+------------
+
+SDC distribution client is delivered as a jar library and hosted on https://nexus.onap.org/
+
+To include it as a dependency in your project, see `SDC Distribution Client mvn`_.
+
+.. _SDC Distribution Client mvn: https://mvnrepository.com/artifact/org.onap.sdc.sdc-distribution-client/sdc-distribution-client
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
new file mode 100644
index 0000000..7e59f76
--- /dev/null
+++ b/docs/sections/offeredapis.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _api_docs:
+
+Offered APIs
+============
+
+The api javadocs for interfaces provided by the sdc distribution client can be compiled by building the project.
+
+See :ref:`build steps<Build Steps>` for more information.
+
+The javadocs can be then found under the ``sdc-distribution-client/target/apidocs`` folder.
+
+The main interface that must be implemented by clients is the IConfiguration interface.
+
+See the :ref:`configuration section<config>` configuration section for more details.
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644
index 0000000..cf7b0cf
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,105 @@
+.. This work is licensed under a Creative Commons Attribution 4.0
+   International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2022 Nordix Foundation
+
+.. _release_notes:
+
+
+..      ===========================
+..      * * *      LONDON     * * *
+..      ===========================
+
+
+*************
+Release Notes
+*************
+
+..
+   * The release note needs to be updated for each ONAP release
+   * Except the section "Release data" all other sections are optional and should be
+     applied where applicable
+   * Only the current release is to be documented in this document
+   * This note needs to be removed before publishing the final result
+
+
+London
+========
+
+
+Abstract
+========
+
+This document provides the release notes for the London release.
+
+Summary
+=======
+Client migration to use kafka as it's main messaging bus to publish and subscribe to the
+SDC distribution topics.
+Removal of all interaction with DMaaP Message Router apis.
+
+Release Data
+============
+
++--------------------------------------+--------------------------------------+
+| **Project**                          | sdc/sdc-distribution-client          |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+| **Jars**                             |  sdc-distribution-client 2.0.0       |
+|                                      |                                      |
++--------------------------------------+--------------------------------------+
+
+New features
+------------
+Modify client to use kafka native to publish and subscribe to SDC topics
+https://jira.onap.org/browse/DMAAP-1745
+
+Deliverables
+------------
+
+Software Deliverables
+~~~~~~~~~~~~~~~~~~~~~
+
+..  code-block:: xml
+
+    <groupId>org.onap.sdc.sdc-distribution-client</groupId>
+    <artifactId>sdc-distribution-client</artifactId>
+    <version>2.0.0</version>
+
+Known Limitations, Issues and Workarounds
+=========================================
+
+System Limitations
+------------------
+NA
+
+Known Vulnerabilities
+---------------------
+NA
+
+Workarounds
+-----------
+NA
+
+Security Notes
+--------------
+NA
+
+References
+==========
+
+For more information on the ONAP London release, please see:
+
+#. `ONAP Home Page`_
+#. `ONAP Documentation`_
+#. `ONAP Release Downloads`_
+#. `ONAP Wiki Page`_
+#. `SDC ReadTheDocs`_
+#. `SDC Portal`_
+
+.. _`ONAP Home Page`: https://www.onap.org
+.. _`ONAP Wiki Page`: https://wiki.onap.org
+.. _`ONAP Documentation`: https://docs.onap.org
+.. _`ONAP Release Downloads`: https://git.onap.org
+.. _`SDC ReadTheDocs`: https://docs.onap.org/projects/onap-sdc/en/latest/
+.. _`SDC Portal`: https://wiki.onap.org/display/DW/Service+Design+and+Creation+%28SDC%29+Portal
diff --git a/docs/tox.ini b/docs/tox.ini
index edac8c3..6e1245c 100644
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -1,22 +1,32 @@
 [tox]
 minversion = 1.6
-envlist = docs,
+envlist = docs,docs-linkcheck,docs-spellcheck
 skipsdist = true
 
 [testenv:docs]
-basepython = python3
-deps = -r{toxinidir}/requirements-docs.txt
+basepython = python3.8
+deps =
+    -r{toxinidir}/requirements-docs.txt
+    -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
+    -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
 commands =
-    sphinx-build -b html -n -d {envtmpdir}/doctrees ./ {toxinidir}/_build/html
-    echo "Generated docs available in {toxinidir}/_build/html"
-whitelist_externals =
-    echo
-    git
-    sh
+    sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html
 
 [testenv:docs-linkcheck]
-basepython = python3
-#deps = -r{toxinidir}/requirements-docs.txt
-commands = echo "Link Checking not enforced"
-#commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./ {toxinidir}/_build/linkcheck
-whitelist_externals = echo
+basepython = python3.8
+deps =
+    -r{toxinidir}/requirements-docs.txt
+    -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
+    -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
+commands =
+    sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck
+
+[testenv:docs-spellcheck]
+basepython = python3.8
+deps =
+    -r{toxinidir}/requirements-docs.txt
+    -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt
+    -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master
+commands =
+    sphinx-build -W -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck
+