From 090941b572c917d8e84ea709eb3696fdc8f53be1 Mon Sep 17 00:00:00 2001 From: Sylvain Desbureaux Date: Wed, 9 Dec 2020 10:13:42 +0100 Subject: [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 Change-Id: I318718c956020412a120ba3caeb9e21d35a99833 (cherry picked from commit ec07bca720e5e2156be085e89f1ce8521a602eaf) --- docs/conf.py | 24 ++++++++++++++++++++++++ docs/oom_quickstart_guide.rst | 5 +++-- docs/oom_setup_ingress_controller.rst | 2 +- docs/oom_user_guide.rst | 5 +++-- docs/oom_user_guide_helm3.rst | 8 ++++---- docs/requirements-docs.txt | 1 + tox.ini | 19 +++++++++++++++++++ 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=] 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=] 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://:30270/ui/ +To see the real-time health of a deployment go to: ``http://: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 = -- cgit 1.2.3-korg