Restructure CLAMP documentation tree

Restructured and refactored the CLAMP documentation
- Introduced a hierarchical structure to the documentaiton
- Added a tree for builtin and TOSCA CLAMP
- Cleaned up formatting
- Added documentation for participants
- Added placeholders for missing particioant, control loop runtime,
  and control loop GUI documentation
- Fixed some hanging references

Issue-ID: POLICY-3363
Change-Id: I3933be08af3984f2bb4e08707a8c5b5b454f540c
Signed-off-by: liamfallon <liam.fallon@est.tech>

9 files changed, 210 insertions, 0 deletions

diff --git a/docs/clamp/controlloop/design-impl/clamp-controlloop-runtime.rst b/docs/clamp/controlloop/design-impl/clamp-controlloop-runtime.rst
new file mode 100644
index 00000000..5bea627f
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/clamp-controlloop-runtime.rst
@@ -0,0 +1,8 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-runtime:
+
+The CLAMP Control Loop Runtime
+##############################
+
+To be completed.
diff --git a/docs/clamp/controlloop/design-impl/clamp-gui-controlloop.rst b/docs/clamp/controlloop/design-impl/clamp-gui-controlloop.rst
new file mode 100644
index 00000000..9064889b
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/clamp-gui-controlloop.rst
@@ -0,0 +1,8 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-gui-controlloop:
+
+The CLAMP GUI for Control Loops
+###############################
+
+To be completed.
diff --git a/docs/clamp/controlloop/design-impl/design-impl.rst b/docs/clamp/controlloop/design-impl/design-impl.rst
new file mode 100644
index 00000000..50ebb2e7
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/design-impl.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-design-impl:
+
+CLAMP TOSCA Control Loop Components: Design and Implementaiton
+##############################################################
+
+The sections below describe the components that handle TOSCA Control Loops.
+
+.. toctree::
+   :maxdepth: 1
+
+   clamp-controlloop-runtime
+   clamp-gui-controlloop
+   participants/participants
diff --git a/docs/clamp/controlloop/design-impl/participants/http-participant.rst b/docs/clamp/controlloop/design-impl/participants/http-participant.rst
new file mode 100644
index 00000000..87f0ec6f
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/participants/http-participant.rst
@@ -0,0 +1,103 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-http-participant:
+
+HTTP Participant
+################
+
+.. warning:: To be completed
+
+The CLAMP HTTP participant receives configuration information from the CLAMP runtime,
+maps the configuration information to a REST URL, and makes a REST call on the URL.
+Typically the HTTP Participant is used with another participant such as the
+:ref:`Kubernetes Participant <clamp-controlloop-k8s-participant>`, which brings up
+the microservice that runs a REST server. Once the microservice is up, the HTTP
+participant can be used to configure the microservice over its REST interface.Of course,
+the HTTP participant works towards any REST service, it is not restricted to REST
+services started by participants.
+
+.. image:: ../../images/participants/http-participant.png
+
+The HTTP participant runs a Control Loop Element to handle the REST dialogues for a
+particular application domain. The REST dialogues are whatever REST calls that are
+required to implement the functionality for the application domain.
+
+The HTTP participant allows the REST dialogues for a Control Loop to be managed. A
+particular Control Loop may require many *things* to be configured and managed and this
+may require many REST dialogues to achieve.
+
+A *Configuration Entity* describes a concept that is managed by the HTTP participant. A
+Configuration Entity can be created, Read, Updated, and Deleted (CRUD). The user defines
+the Configuration Entities that it wants its HTTP Control Loop Element to manage and
+provides a sequence of parameterized REST commands to Create, Read, Update, and Delete
+each Configuration Entity.
+
+When a control loop is initialized, the HTTP participant starts a HTTP Control Loop
+element for the control loop. It reads the configuration information sent from the
+Control Loop Runtime runs a HTTP client to talk to the REST endpoint that is receiving
+the REST requests. A HTTP participant can simultaneously manage HTTP Control Loop
+Elements towards multiple REST endpoints, as shown in the diagram above where the HTTP
+participant is running two HTTP Control Loop Elements, one for Control Loop A and one for
+Control Loop B.
+
+Configuring a Control Loop Element on the HTTP participant for a Control Loop
+-----------------------------------------------------------------------------
+
+The user configures the following properties in the CLAMP GUI for the HTTP participant:
+
+.. list-table::
+   :widths: 15 10 50
+   :header-rows: 1
+
+   * - Property
+     - Type
+     - Description
+   * - baseUrl
+     - URL
+     - A well formed URL pointing at the REST server that is processing the REST requests
+   * - httpHeaders
+     - map
+     - A map of *<String, String>* defining the HTTP headers to send on all REST calls
+   * - configurationEntitiies
+     - map
+     - A map of *<String, ConfigurationEntity>* describing the names and definitions of
+       configuration entities that are managed by this HTTP Control Loop Element
+
+The *ConfigurationEntity* type is described in the following table:
+
+.. list-table::
+   :widths: 15 10 50
+   :header-rows: 1
+
+   * - Field
+     - Type
+     - Description
+   * - ID
+     - ToscaConceptIdentifier
+     - The name and version of the Configuration Entity
+   * - restSequence
+     - List<RestRequest>
+     - A list of REST requests to give manage the Configuration Entity
+
+The *RestRequest* type is described in the following table:
+
+.. list-table::
+   :widths: 15 10 50
+   :header-rows: 1
+
+   * - Field
+     - Type
+     - Description
+   * - httpMethod
+     - HttpMethod
+     - An enum for the HTTP method {GET, PUT, POST, DELETE}
+   * - path
+     - String
+     - The path of the REST endopint relative to the baseUrl
+   * - body
+     - String
+     - The body of the request for POST and PUT methods
+   * - expectedResponse
+     - HttpStatus
+     - The expected HTTP response code fo the REST request
+ 
\ No newline at end of file
diff --git a/docs/clamp/controlloop/design-impl/participants/k8s-participant.rst b/docs/clamp/controlloop/design-impl/participants/k8s-participant.rst
new file mode 100644
index 00000000..1e1a05a3
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/participants/k8s-participant.rst
@@ -0,0 +1,8 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-k8s-participant:
+
+Kubernetes Participant
+######################
+
+.. warning:: To be completed
diff --git a/docs/clamp/controlloop/design-impl/participants/participant-intermediary.rst b/docs/clamp/controlloop/design-impl/participants/participant-intermediary.rst
new file mode 100644
index 00000000..7f6cf499
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/participants/participant-intermediary.rst
@@ -0,0 +1,13 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-participant-intermediary:
+
+Participant Intermediary
+########################
+
+The CLAMP Participant Intermediary is a common library in ONAP, which does common message and
+state handling for participant implementations. It provides a Java API, which participant
+implementations implement to receive and send messages to the CLAMP runtime and to handle
+Control Loop Element state.
+
+.. warning:: To be completed
diff --git a/docs/clamp/controlloop/design-impl/participants/participant-simulator.rst b/docs/clamp/controlloop/design-impl/participants/participant-simulator.rst
new file mode 100644
index 00000000..8f59a9f1
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/participants/participant-simulator.rst
@@ -0,0 +1,8 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-participant-simulator:
+
+Participant Simulator
+#####################
+
+To be completed.
diff --git a/docs/clamp/controlloop/design-impl/participants/participants.rst b/docs/clamp/controlloop/design-impl/participants/participants.rst
new file mode 100644
index 00000000..230c9888
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/participants/participants.rst
@@ -0,0 +1,39 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-participants:
+
+Control Loop Participants
+#########################
+
+A Participant is a component that acts as a bridge between the CLAMP COntrol Loop runtime and components such as
+the Policy Framework, DCAE, or a Kubernetes cluster that are taking part in control loops. It listens
+to DMaaP to receive messages from the CLAMP runtime and performs operations towards components that
+are taking part in control loops. A participant has a Control Loop Element for each control loop in
+which it is taking part.
+
+The implementation of a participant may use a common
+:ref:`Participant Intermediary library <clamp-controlloop-participant-intermediary>`, which carries out common
+message and state handling for Control Loop Elements in participants. The *ParticipantImpelementation* is the
+component specific implementation of a participant, which is specifically developed for each component that
+wishes to take part in control loops.
+
+.. image:: ../../images/participants/participants.png
+
+The figure above shows participants for various components that may take part in control loops.
+
+.. note:: The figure above is for illustration. Not all the participants mentioned above
+          have realizations in ONAP. Some of the participants in the figure above represent
+          a type of participant. For example, a controller participant would be written for
+          a specific controller such as CDS and a participant for an existing system would be
+          written towards that existing system.
+
+The detailed implementation of the CLAMP Participant ecosystem is described on the following pages:
+
+.. toctree::
+   :maxdepth: 1
+
+   participant-intermediary
+   http-participant
+   k8s-participant
+   policy-framework-participant
+   participant-simulator
diff --git a/docs/clamp/controlloop/design-impl/participants/policy-framework-participant.rst b/docs/clamp/controlloop/design-impl/participants/policy-framework-participant.rst
new file mode 100644
index 00000000..746dd529
--- /dev/null
+++ b/docs/clamp/controlloop/design-impl/participants/policy-framework-participant.rst
@@ -0,0 +1,8 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _clamp-controlloop-policy-framework-participant:
+
+Policy Framework Participant
+############################
+
+To be completed.