[COMMON] Add doc linting

Add 3 automated doc linting (sphinx building, linkchecking and doc8) in
order to have an error free documentations
Fix also issues found by these linters in order to start without errors.

Issue-ID: OOM-2648
Signed-off-by: Sylvain Desbureaux <sylvain.desbureaux@orange.com>
Change-Id: I318718c956020412a120ba3caeb9e21d35a99833
(cherry picked from commit ec07bca720e5e2156be085e89f1ce8521a602eaf)

7 files changed, 55 insertions, 9 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 3b28eb74a8..a45acf370f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,6 +9,30 @@ linkcheck_ignore = [
 
 intersphinx_mapping = {}
 
+needs_services = {
+    'github-issues': {
+        'url': 'https://api.github.com/',
+        'need_type': 'spec',
+        'max_amount': 2,
+        'max_content_lines': 20,
+        'id_prefix': 'GH_ISSUE_'
+    },
+    'github-prs': {
+        'url': 'https://api.github.com/',
+        'need_type': 'spec',
+        'max_amount': 2,
+        'max_content_lines': 20,
+        'id_prefix': 'GH_PR_'
+    },
+    'github-commits': {
+        'url': 'https://api.github.com/',
+        'need_type': 'spec',
+        'max_amount': 2,
+        'max_content_lines': 20,
+        'id_prefix': 'GH_COMMIT_'
+    }
+}
+
 html_last_updated_fmt = '%d-%b-%y %H:%M'
 
 def setup(app):
diff --git a/docs/oom_quickstart_guide.rst b/docs/oom_quickstart_guide.rst
index 6b1c69cc44..51c28c2ca3 100644
--- a/docs/oom_quickstart_guide.rst
+++ b/docs/oom_quickstart_guide.rst
@@ -161,8 +161,9 @@ follows::
   > make SKIP_LINT=TRUE [HELM_BIN=<HELM_PATH>] all
 
 `HELM_BIN`
-  Sets the helm binary to be used. The default value use helm from PATH. Allow the user to have
-  multiple version of helm in operating system and choose which one to use.
+  Sets the helm binary to be used. The default value use helm from PATH. Allow
+  the user to have multiple version of helm in operating system and choose
+  which one to use.
 
 **Step 7.** Display the onap charts that available to be deployed::
 
diff --git a/docs/oom_setup_ingress_controller.rst b/docs/oom_setup_ingress_controller.rst
index c15171c7be..29dac92c95 100644
--- a/docs/oom_setup_ingress_controller.rst
+++ b/docs/oom_setup_ingress_controller.rst
@@ -15,7 +15,7 @@
 .. figure:: oomLogoV2-medium.png
    :align: right
 
-.. _onap-on-kubernetes-with-rancher:
+.. _oom_setup_ingress_controller:
 
 
 Ingress controller setup on HA Kubernetes Cluster
diff --git a/docs/oom_user_guide.rst b/docs/oom_user_guide.rst
index ac716a3eb7..9aac8aefb6 100644
--- a/docs/oom_user_guide.rst
+++ b/docs/oom_user_guide.rst
@@ -142,8 +142,9 @@ Then build your local Helm repository::
   > make SKIP_LINT=TRUE [HELM_BIN=<HELM_PATH>] all
 
 `HELM_BIN`
-  Sets the helm binary to be used. The default value use helm from PATH. Allow the user to have
-  multiple version of helm in operating system and choose which one to use.
+  Sets the helm binary to be used. The default value use helm from PATH.
+  Allow the user to have multiple version of helm in operating system and
+  choose which one to use.
 
 The Helm search command reads through all of the repositories configured on the
 system, and looks for matches::
diff --git a/docs/oom_user_guide_helm3.rst b/docs/oom_user_guide_helm3.rst
index b687fe8bd3..08e9ec0d0b 100644
--- a/docs/oom_user_guide_helm3.rst
+++ b/docs/oom_user_guide_helm3.rst
@@ -12,8 +12,8 @@
 .. _Helm Documentation: https://docs.helm.sh/helm/
 .. _Helm: https://docs.helm.sh/
 .. _Kubernetes: https://Kubernetes.io/
-.. _Kubernetes LoadBalancer: https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer
-.. _user-guide-label:
+.. _Kubernetes LoadBalancer: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer
+.. _oom_user_guide_helm3:
 
 OOM User Guide helm3 (experimental)
 ###################################
@@ -415,7 +415,7 @@ below::
 
 Ensure you've disabled any proxy settings the browser you are using to access
 the portal and then simply access now the new ssl-encrypted URL:
-https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm
+``https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm``
 
 .. note::
   Using the HTTPS based Portal URL the Browser needs to be configured to accept
@@ -482,7 +482,7 @@ have been created - a sample from the ONAP Integration labs follows:
 .. figure:: consulHealth.png
    :align: center
 
-To see the real-time health of a deployment go to: http://<kubernetes IP>:30270/ui/
+To see the real-time health of a deployment go to: ``http://<kubernetes IP>:30270/ui/``
 where a GUI much like the following will be found:
 
 
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
index b3188ddd38..e14c784ee4 100644
--- a/docs/requirements-docs.txt
+++ b/docs/requirements-docs.txt
@@ -8,6 +8,7 @@ sphinx_rtd_theme>=0.4.3
 sphinxcontrib-blockdiag
 sphinxcontrib-needs>=0.2.3
 sphinxcontrib-nwdiag
+sphinxcontrib-redoc
 sphinxcontrib-seqdiag
 sphinxcontrib-swaggerdoc
 sphinxcontrib-plantuml
diff --git a/tox.ini b/tox.ini
index 60f93a35e4..c685a3fdd2 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,9 +1,28 @@
 [tox]
 minversion = 1.6
 envlist =
+ docs,
+ docs-linkcheck,
  gitlint,
 skipsdist=true
 
+[doc8]
+ignore-path-errors=docs/helm-search.txt;D001
+
+[testenv:doc8]
+deps = -rdocs/requirements-docs.txt
+commands =
+ doc8 docs/
+
+[testenv:docs]
+deps = -rdocs/requirements-docs.txt
+commands =
+ sphinx-build -W -b html -n -W -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+
+[testenv:docs-linkcheck]
+deps = -rdocs/requirements-docs.txt
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
+
 [testenv:gitlint]
 basepython = python3
 deps =