From d5b0873f98edb8099744975597a104c199852f9a Mon Sep 17 00:00:00 2001 From: Georg Kunz Date: Wed, 21 Oct 2020 21:12:46 +0200 Subject: Added structure for OPNFV documentation Having this structure in place is a requirement for passing release milestone M2. This change does not modify the content of the current documentation / deployment guide. Signed-off-by: Georg Kunz Change-Id: I07e8820901970da1199f4a474161e49f25707ecc Reviewed-on: https://gerrit.opnfv.org/gerrit/c/kuberef/+/71298 Tested-by: jenkins-ci Reviewed-by: Michael Pedersen Reviewed-by: Sofia Wallin --- .gitignore | 1 + docs/conf.py | 6 +++ docs/conf.yaml | 3 ++ docs/deployment-guide.rst | 60 -------------------------- docs/index.rst | 18 ++++++++ docs/release/installation/deployment-guide.rst | 60 ++++++++++++++++++++++++++ docs/release/installation/index.rst | 17 ++++++++ docs/release/release-notes/index.rst | 17 ++++++++ docs/release/release-notes/release-notes.rst | 8 ++++ docs/requirements.txt | 2 + tox.ini | 11 +++++ 11 files changed, 143 insertions(+), 60 deletions(-) create mode 100644 docs/conf.py create mode 100644 docs/conf.yaml delete mode 100644 docs/deployment-guide.rst create mode 100644 docs/index.rst create mode 100644 docs/release/installation/deployment-guide.rst create mode 100644 docs/release/installation/index.rst create mode 100644 docs/release/release-notes/index.rst create mode 100644 docs/release/release-notes/release-notes.rst create mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore index 01a8308..7b15083 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ inventory/group_vars/all/pdf.yaml images workspace .tox +docs/_build/ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b281a51 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,6 @@ +""" for docs +""" + +# pylint: disable=import-error +# flake8: noqa +from docs_conf.conf import * diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..a9bc5de --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: opnfv +project: Kuberef diff --git a/docs/deployment-guide.rst b/docs/deployment-guide.rst deleted file mode 100644 index 0875bcf..0000000 --- a/docs/deployment-guide.rst +++ /dev/null @@ -1,60 +0,0 @@ -=================================== -Welcome to Kuberef's documentation! -=================================== - -Introduction -============ - -Kuberef aims to develop and deliver a Kubernetes-based reference -implementation according to CNTT RA-2 in close collaboration with the -CNTT RI-2 workstream. - -The entire implementation is divided into two stages - Host provisioning -and Kubernetes provisioning. - -This guide describes how to get started with a potential RI-2 deployment -using `Cloud Infra Automation Framework `_ -for the Host provisioning stage and Intel's `BMRA `_ -for the Kubernetes provisioning stage. - -.. note:: - - This is just an example of a possible RI-2 deployment. Kuberef aims to - support and include other potential hardware and Kubernetes deployers as well. More - details can be found in the `Kuberef Wiki `_. - -Infrastructure Prerequisites -============================= - -You need one physical server acting as a jump server along with minimum of two additional -servers on which RI-2 will be deployed. Please refer to Chapter 3 in CNTT RI-2 Documentation -for detailed information on the server and network specifications. - -Additionally, please make sure that you have KVM installed and set up on your jump server. This -is needed because the deployment will spin up a VM which will then carry out the host and -Kubernetes installation. - -Deployment -============================= - -Before initiating the deployment, please note the following: - -1. Add your configuration templates, ``pdf.yaml`` and ``idf.yaml`` under ``hw_config/``. - -2. Modify the environmental variables defined in ``deploy.env`` to match your setup. - -3. Update ``hw_config//setup_network.sh`` with your correct networking info. This particular - script sets up networking on the provisioned nodes after the host provisioning stage is successful. - -.. note:: - - Depending on your setup, this script might not be needed. #WIP - -Once ready, issue the following command to initiate the deployment - -.. code-block:: bash - - ./deploy.sh - - -Once the deployment is successful, you will have a fully functional RI-2 setup! diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..22eafd4 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,18 @@ +.. _kuberef: + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. SPDX-License-Identifier CC-BY-4.0 +.. (c) OPNFV, Ericsson AB and others + +********************************* +OPNFV Kuberef +********************************* + +.. toctree:: + :numbered: + :maxdepth: 3 + + release/release-notes/index + release/installation/index + diff --git a/docs/release/installation/deployment-guide.rst b/docs/release/installation/deployment-guide.rst new file mode 100644 index 0000000..0875bcf --- /dev/null +++ b/docs/release/installation/deployment-guide.rst @@ -0,0 +1,60 @@ +=================================== +Welcome to Kuberef's documentation! +=================================== + +Introduction +============ + +Kuberef aims to develop and deliver a Kubernetes-based reference +implementation according to CNTT RA-2 in close collaboration with the +CNTT RI-2 workstream. + +The entire implementation is divided into two stages - Host provisioning +and Kubernetes provisioning. + +This guide describes how to get started with a potential RI-2 deployment +using `Cloud Infra Automation Framework `_ +for the Host provisioning stage and Intel's `BMRA `_ +for the Kubernetes provisioning stage. + +.. note:: + + This is just an example of a possible RI-2 deployment. Kuberef aims to + support and include other potential hardware and Kubernetes deployers as well. More + details can be found in the `Kuberef Wiki `_. + +Infrastructure Prerequisites +============================= + +You need one physical server acting as a jump server along with minimum of two additional +servers on which RI-2 will be deployed. Please refer to Chapter 3 in CNTT RI-2 Documentation +for detailed information on the server and network specifications. + +Additionally, please make sure that you have KVM installed and set up on your jump server. This +is needed because the deployment will spin up a VM which will then carry out the host and +Kubernetes installation. + +Deployment +============================= + +Before initiating the deployment, please note the following: + +1. Add your configuration templates, ``pdf.yaml`` and ``idf.yaml`` under ``hw_config/``. + +2. Modify the environmental variables defined in ``deploy.env`` to match your setup. + +3. Update ``hw_config//setup_network.sh`` with your correct networking info. This particular + script sets up networking on the provisioned nodes after the host provisioning stage is successful. + +.. note:: + + Depending on your setup, this script might not be needed. #WIP + +Once ready, issue the following command to initiate the deployment + +.. code-block:: bash + + ./deploy.sh + + +Once the deployment is successful, you will have a fully functional RI-2 setup! diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst new file mode 100644 index 0000000..fe2d1af --- /dev/null +++ b/docs/release/installation/index.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB and others. + +.. _kubref-releasenotes: + +================================================== +Kuberef Installation Guide +================================================== + +.. toctree:: + :numbered: + :maxdepth: 2 + + deployment-guide.rst + +Build date: |today| diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst new file mode 100644 index 0000000..41e6ab3 --- /dev/null +++ b/docs/release/release-notes/index.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB and others. + +.. _kubref-releasenotes: + +================================================== +Kuberef Release Notes +================================================== + +.. toctree:: + :numbered: + :maxdepth: 2 + + release-notes.rst + +Build date: |today| diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst new file mode 100644 index 0000000..c592e8b --- /dev/null +++ b/docs/release/release-notes/release-notes.rst @@ -0,0 +1,8 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Ericsson AB and others. + +Jerma Release +------------- + +TBD diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..9fde2df --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +lfdocs-conf +sphinx_opnfv_theme diff --git a/tox.ini b/tox.ini index 53ab1a7..0d309d7 100644 --- a/tox.ini +++ b/tox.ini @@ -18,3 +18,14 @@ commands = bash -c "find {toxinidir} \ bash -c "find {toxinidir} \ -not -path {toxinidir}/.tox/\* \ -name \*.rst | xargs rstcheck" + +[testenv:docs] +deps = -rdocs/requirements.txt +commands = + sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +whitelist_externals = echo + +[testenv:docs-linkcheck] +deps = -rdocs/requirements.txt +commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck -- cgit 1.2.3-korg