[DMAAP-BC] Update RTD setup files
Signed-off-by: efiacor <fiachra.corcoran@est.tech>
Change-Id: I0e03f3ed682e319c496b303462732c71436ae6d5
Issue-ID: DMAAP-1824
(cherry picked from commit 86532163d19990e3acfa645a367ed0e0a1c787e0)
diff --git a/.gitreview b/.gitreview
index 1b82e85..f1c9920 100644
--- a/.gitreview
+++ b/.gitreview
@@ -2,3 +2,4 @@
host=gerrit.onap.org
port=29418
project=dmaap/buscontroller.git
+defaultbranch=kohn
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 3797dc8..fa15a7c 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -2,12 +2,8 @@
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-# Required
version: 2
-formats:
- - htmlzip
-
build:
image: latest
@@ -16,5 +12,8 @@
install:
- requirements: docs/requirements-docs.txt
+submodules:
+ include: all
+
sphinx:
configuration: docs/conf.py
diff --git a/docs/_static/css/ribbon.css b/docs/_static/css/ribbon.css
index 6008cb1..7342cdc 100644
--- a/docs/_static/css/ribbon.css
+++ b/docs/_static/css/ribbon.css
@@ -59,5 +59,5 @@
/* fix width of the screen */
.wy-nav-content {
- max-width: none;
-}
+ max-width: 800px;
+}
\ No newline at end of file
diff --git a/docs/apis/api.rst b/docs/apis/api.rst
index 7379556..ffd711e 100644
--- a/docs/apis/api.rst
+++ b/docs/apis/api.rst
@@ -28,7 +28,7 @@
dcaeLocation. MR_Clients generally communicate to the
MR_Cluster at the same dcaeLocation. Replication of messages
between MR_Clusters is accomplished by MR Bridge, which is
- provioned by DMaaP Bus Controller based on Topic attributes.
+ provisioned by DMaaP Bus Controller based on Topic attributes.
Therefore, the role of DMaaP Bus Controller is to support other
DCAE infrastructure components to dynamically provision DMaaP
@@ -64,13 +64,12 @@
~~~~~~~~
http://www.[host]:[port]/webapi
-https://www.[host]:[port]/webapi
BRIDGE
~~~~~~
-Endpoint for retreiving MR Bridge metrics
+Endpoint for retrieving MR Bridge metrics
@@ -4031,7 +4030,7 @@
~~~~~~
-Endpoint for retreiving MR Topics
+Endpoint for retrieving MR Topics
diff --git a/docs/apis/swagger.json b/docs/apis/swagger.json
index ceb041f..742006b 100644
--- a/docs/apis/swagger.json
+++ b/docs/apis/swagger.json
@@ -1,7 +1,7 @@
{
"swagger" : "2.0",
"info" : {
- "description" : "provides an API for OpenDCAE components which need to provision\n\t\t\t\t\t\t\t\t\tunderlying DMaaP technologies (Data Router and Message Router).\n\t\t\t\t\t\t\t\t\tPrimary clients for this API are anticipated to be the OpenDCAE\n\t\t\t\t\t\t\t\t\tController, OpenDCAE Orchestrator, OpenDCAE Inventory and the\n\t\t\t\t\t\t\t\t\tECOMP Portal.\n\n\t\t\t\t\t\t\t\t\tObjects managed by DMaaP are deployed in a dcaeLocation which is a\n\t\t\t\t\t\t\t\t\tunique identifier for an OpenStack tenant for a dcaeLayer,\n\t\t\t\t\t\t\t\t\topendcae-central (aka ecomp) or opendcae-local-ntc (aka edge).\n\n\t\t\t\t\t\t\t\t\tA dcaeEnvironment (e.g. FTL or prod) has a single DMaaP. A\n\t\t\t\t\t\t\t\t\tDMaaP is managed by a one or more stateless DMaaP Bus\n\t\t\t\t\t\t\t\t\tController(s), though Bus Controller relies on PGaaS for\n\t\t\t\t\t\t\t\t\tpersistence. Each DMaaP has a single instance of Data Router,\n\t\t\t\t\t\t\t\t\twhich has 1 or more DR_Nodes deployed at each dcaeLocation. DR\n\t\t\t\t\t\t\t\t\tClients of type DR_Pub generally publish to a DR_Node that is\n\t\t\t\t\t\t\t\t\tlocal to its dcaeLocation. Routing for a Feed is determined by\n\t\t\t\t\t\t\t\t\tthe dcaelocation of its DR_Sub clients.\n\n\t\t\t\t\t\t\t\t\tA DMaaP may have many Message Router instances. Each instance is\n\t\t\t\t\t\t\t\t\tdeployed as an MR_Cluster. One MR_Cluster is deployed at each\n\t\t\t\t\t\t\t\t\tdcaeLocation. MR_Clients generally communicate to the\n\t\t\t\t\t\t\t\t\tMR_Cluster at the same dcaeLocation. Replication of messages\n\t\t\t\t\t\t\t\t\tbetween MR_Clusters is accomplished by MR Bridge, which is\n\t\t\t\t\t\t\t\t\tprovioned by DMaaP Bus Controller based on Topic attributes.\n\n\t\t\t\t\t\t\t\t\tTherefore, the role of DMaaP Bus Controller is to support other\n\t\t\t\t\t\t\t\t\tDCAE infrastructure components to dynamically provision DMaaP\n\t\t\t\t\t\t\t\t\tservices on behalf of DMaaP clients, and to assist in any\n\t\t\t\t\t\t\t\t\tmanagement or discovery activity of its clients.\n\n\t\t\t\t\t\t\t\t\tA convention of this API is to return JSON responses per\n\t\t\t\t\t\t\t\t\tOpenStack style.",
+ "description" : "provides an API for OpenDCAE components which need to provision\n\t\t\t\t\t\t\t\t\tunderlying DMaaP technologies (Data Router and Message Router).\n\t\t\t\t\t\t\t\t\tPrimary clients for this API are anticipated to be the OpenDCAE\n\t\t\t\t\t\t\t\t\tController, OpenDCAE Orchestrator, OpenDCAE Inventory and the\n\t\t\t\t\t\t\t\t\tECOMP Portal.\n\n\t\t\t\t\t\t\t\t\tObjects managed by DMaaP are deployed in a dcaeLocation which is a\n\t\t\t\t\t\t\t\t\tunique identifier for an OpenStack tenant for a dcaeLayer,\n\t\t\t\t\t\t\t\t\topendcae-central (aka ecomp) or opendcae-local-ntc (aka edge).\n\n\t\t\t\t\t\t\t\t\tA dcaeEnvironment (e.g. FTL or prod) has a single DMaaP. A\n\t\t\t\t\t\t\t\t\tDMaaP is managed by a one or more stateless DMaaP Bus\n\t\t\t\t\t\t\t\t\tController(s), though Bus Controller relies on PGaaS for\n\t\t\t\t\t\t\t\t\tpersistence. Each DMaaP has a single instance of Data Router,\n\t\t\t\t\t\t\t\t\twhich has 1 or more DR_Nodes deployed at each dcaeLocation. DR\n\t\t\t\t\t\t\t\t\tClients of type DR_Pub generally publish to a DR_Node that is\n\t\t\t\t\t\t\t\t\tlocal to its dcaeLocation. Routing for a Feed is determined by\n\t\t\t\t\t\t\t\t\tthe dcaelocation of its DR_Sub clients.\n\n\t\t\t\t\t\t\t\t\tA DMaaP may have many Message Router instances. Each instance is\n\t\t\t\t\t\t\t\t\tdeployed as an MR_Cluster. One MR_Cluster is deployed at each\n\t\t\t\t\t\t\t\t\tdcaeLocation. MR_Clients generally communicate to the\n\t\t\t\t\t\t\t\t\tMR_Cluster at the same dcaeLocation. Replication of messages\n\t\t\t\t\t\t\t\t\tbetween MR_Clusters is accomplished by MR Bridge, which is\n\t\t\t\t\t\t\t\t\tprovisioned by DMaaP Bus Controller based on Topic attributes.\n\n\t\t\t\t\t\t\t\t\tTherefore, the role of DMaaP Bus Controller is to support other\n\t\t\t\t\t\t\t\t\tDCAE infrastructure components to dynamically provision DMaaP\n\t\t\t\t\t\t\t\t\tservices on behalf of DMaaP clients, and to assist in any\n\t\t\t\t\t\t\t\t\tmanagement or discovery activity of its clients.\n\n\t\t\t\t\t\t\t\t\tA convention of this API is to return JSON responses per\n\t\t\t\t\t\t\t\t\tOpenStack style.",
"version" : "1.1.0",
"title" : "DMaaP Bus Controller REST API",
"termsOfService" : "http://www.apache.org/licenses/LICENSE-2.0",
@@ -26,7 +26,7 @@
"description" : "Endpoint for a Message Router servers in a Cluster configuration"
}, {
"name" : "bridge",
- "description" : "Endpoint for retreiving MR Bridge metrics"
+ "description" : "Endpoint for retrieving MR Bridge metrics"
}, {
"name" : "dcaeLocations",
"description" : "an OpenStack tenant purposed for OpenDCAE (i.e. where OpenDCAE components might be deployed)"
@@ -47,7 +47,7 @@
"description" : "Endpoint for this instance of DBCL. Returns health info."
}, {
"name" : "topics",
- "description" : "Endpoint for retreiving MR Topics"
+ "description" : "Endpoint for retrieving MR Topics"
} ],
"schemes" : [ "http", "https" ],
"paths" : {
diff --git a/docs/conf.py b/docs/conf.py
index bd96005..909d8b8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,27 +1,58 @@
-from docs_conf.conf import *
+project = "onap"
+release = "kohn"
+version = "kohn"
-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"
-intersphinx_mapping = {}
+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
-linkcheck_ignore = [
- 'http://localhost',
- 'https://example.com',
- 'about:config',
- # this URL is not directly reachable and must be configured in the system hosts file.
- 'https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm',
- # anchor issues
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_usecases_release.html#.*',
- 'https://docs.linuxfoundation.org/docs/communitybridge/easycla/contributors/contribute-to-a-gerrit-project#.*',
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_robot.html#docs-robot',
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_usecases_release.html#docs-usecases-release',
- 'https://docs.onap.org/projects/onap-integration/en/latest/docs_usecases.html#docs-usecases',
- 'https://docs.onap.org/projects/onap-integration/en/latest/usecases/release_non_functional_requirements.html#release-non-functional-requirements',
+extensions = [
+ 'sphinx.ext.intersphinx',
+ 'sphinx.ext.graphviz',
+ 'sphinxcontrib.blockdiag',
+ 'sphinxcontrib.seqdiag',
+ 'sphinxcontrib.swaggerdoc',
+ 'sphinxcontrib.plantuml'
]
+#
+# 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 = 'kohn'
+
+intersphinx_mapping = {}
+doc_url = 'https://docs.onap.org/projects'
+master_doc = 'index'
+
+exclude_patterns = ['.tox']
+
+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_css_file("css/ribbon.css")
+
+linkcheck_ignore = [
+ r'http://localhost:\d+/',
+ r'http://www\.\[host]:\[port]/webapi',
+ r'https://gerrit\.onap\.org/'
+]
\ No newline at end of file
diff --git a/docs/conf.yaml b/docs/conf.yaml
deleted file mode 100644
index ab59281..0000000
--- a/docs/conf.yaml
+++ /dev/null
@@ -1,7 +0,0 @@
----
-project_cfg: onap
-project: onap
-
-# Change this to ReleaseBranchName to modify the header
-default-version: latest
-#
diff --git a/docs/installation.rst b/docs/installation.rst
index cee606c..df578e5 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -24,49 +24,69 @@
The Bus Controller is highly configurable, but by default has settings that should work for a standard ONAP oom deployment.
However, if some customization is desired, there are places to change behavior:
-1) The --namespace argument of the helm install step is also refernced to compose the topic namespace used. i.e. the value is appended to org.onap.dmaap. Since Message Router uses org.onap.dmaap.mr by default, we also use --namespace=mr. But this can be changed to a value that matches a different deployment of MR.
+1) The --namespace argument of the helm install step is also referenced to compose the topic namespace used. i.e. the value is appended to org.onap.dmaap. Since Message Router uses org.onap.dmaap.mr by default, we also use --namespace=mr. But this can be changed to a value that matches a different deployment of MR.
2) oom/kubernetes/dmaap/charts/dmaap-bus-controller/values.yaml contains the set of tags used within the charts. These can be modified if necessary.
3) oom/kubernetes/dmaap/charts/dmaap-bus-controller/resources/config/buscontroller.env contains some environment settings for the container. These can be modified. For example, to indicate that AAF integration should be enabled, set USE_AAF=true in this file.
-4) oom/kubernetes/dmaap/charts/dmaap-bus-controller/resources/config/dmaapbc.properties contains many properties which can be modified. For example, if a differerent Postgresql instance needed to be used, the value could be specified here.
+4) oom/kubernetes/dmaap/charts/dmaap-bus-controller/resources/config/dmaapbc.properties contains many properties which can be modified. For example, if a different Postgresql instance needed to be used, the value could be specified here.
Steps for local development and test
------------------------------------
On Intel dev machine, in terminal (> indicates prompt) :
1) Build buscontroller images
+
> git clone https://gerrit.onap.org/r/dmaap/buscontroller
- anonymous http, can't push changes
+
> cd buscontroller
+
> mvn clean install -P docker
+
- builds dmaap-bc and dbc-client images
+
2) Run tests
+
> cd dmaap-bc/src/main/resources/
+
> cp docker-databus-controller.conf /var/tmp/
+
- set docker preferences/file sharing to access /var/tmp
+
- edit docker-compose.yml
- - remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to
- use local images
+
+ - remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to use local images
+
> docker-compose up -d
- create sample.txt file (as above)(content of file not important)
+
> curl http://localhost:30241/webapi/bridge
On Arm:
1) Build buscontroller images
+
> git clone https://gerrit.onap.org/r/dmaap/buscontroller
- anonymous http, can't push changes
+
> cd buscontroller
+
> mvn clean install -P docker -Ddocker.pull.registry=docker.io
- ensure we pull Arm version of base image
+
2) Run tests
+
> cd dmaap-bc/src/main/resources/
+
> cp docker-databus-controller.conf /var/tmp/
- set docker preferences/file sharing to access /var/tmp
+
- edit docker-compose.yml
- remove "nexus3.onap.org:10001/" from dmaap-bc:image: and dbc-client:image: to
use local images
- replace 'crunchydata/crunchy-postgres:centos7-10.4-2.0.0' with
multi-platform 'postgres:9.6-alpine' normative image
+
> docker-compose up -d
- create sample.txt file (as above)(content of file not important)
+
> curl http://localhost:30241/webapi/bridge
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
index c689bdb..fff6cf7 100644
--- a/docs/release-notes.rst
+++ b/docs/release-notes.rst
@@ -275,7 +275,7 @@
New features
------------
-* Updated log4j (Listed in "Known Vulternabilities" below) - DMAAP-1515
+* Updated log4j (Listed in "Known Vulnerabilities" below) - DMAAP-1515
* Update Project Lead details - DMAAP-1538
Known Limitations, Issues and Workarounds
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index 3b3441a..ba3e0ec 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
\ No newline at end of file
diff --git a/docs/security.rst b/docs/security.rst
index aab2c3d..6c648cd 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -203,7 +203,7 @@
-----------------
Usage of AAF can be turned on/off by setting ``UseAAF`` flag to ``true/false`` in the ``dmaapbc.properties`` file. By default AAF usage is turned on.
-Property ``cadi.properties`` points to absolute path of the property file generated by AAF for the DmaaP BC application (``dmaap-bc@dmaap-bc.onap.org`` user).
+Property ``cadi.properties`` points to absolute path of the property file generated by AAF for the DMaaP BC application (``dmaap-bc@dmaap-bc.onap.org`` user).
This file is one of the AAF configuration files enabling authentication and authorization for DMaaP BC REST API.
.. code-block:: bash
diff --git a/docs/tox.ini b/docs/tox.ini
index 49bbe01..1c793f9 100644
--- a/docs/tox.ini
+++ b/docs/tox.ini
@@ -1,6 +1,6 @@
[tox]
minversion = 1.6
-envlist = docs,
+envlist = docs,docs-linkcheck,docs-spellcheck
skipsdist = true
[testenv:docs]
@@ -8,18 +8,24 @@
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
+ -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=kohn
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.8
-#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
+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=kohn
+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=kohn
+commands =
+ sphinx-build -q -b spelling -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/spellcheck
\ No newline at end of file