diff options
53 files changed, 241 insertions, 14 deletions
diff --git a/.gitmodules b/.gitmodules index 846ab2455..f0511b58a 100644 --- a/.gitmodules +++ b/.gitmodules @@ -148,10 +148,6 @@ url = ../qtip branch = . ignore = dirty -[submodule "docs/submodules/releng"] - path = docs/submodules/releng - url = ../releng - branch = master [submodule "docs/submodules/sdnvpn"] path = docs/submodules/sdnvpn url = ../sdnvpn @@ -250,3 +246,8 @@ url = https://gerrit.opnfv.org/gerrit/clover branch = . ignore = dirty +[submodule "docs/submodules/edgecloud"] + path = docs/submodules/edgecloud + url = ../edgecloud + branch = . + ignore = dirty diff --git a/docs/conf.py b/docs/conf.py index 9d9f28168..45de7d635 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -13,7 +13,8 @@ needs_sphinx = '1.3' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['sphinxcontrib.httpdomain', 'sphinx.ext.autodoc', - 'sphinx.ext.viewcode', 'sphinx.ext.napoleon'] + 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', + 'sphinx.ext.intersphinx'] # Disable javasphinx generation until we have a solution to long build # times. readthedocs timesout after 902 seconds. @@ -278,5 +279,5 @@ html_sidebars = {'**': ['localtoc.html', 'relations.html'],} # If true, do not generate a @detailmenu in the "Top" node's menu. # texinfo_no_detailmenu = False -# intersphinx_mapping = -# {'RTD':('http://opnfvdocsdemo.readthedocs.io/projects/', None)} +intersphinx_mapping = {} +intersphinx_mapping['releng'] = ('https://opnfv-releng.readthedocs.io/en/latest', None) diff --git a/docs/featureprojects.rst b/docs/featureprojects.rst index 2f6340baf..d5afec867 100644 --- a/docs/featureprojects.rst +++ b/docs/featureprojects.rst @@ -103,6 +103,12 @@ Doctor ../submodules/doctor/docs/development/design/index ../submodules/doctor/docs/development/manuals/index +Edgecloud +--------- +.. toctree:: + :maxdepth: 1 + + ../submodules/edgecloud/docs/development/requirements/index IPV6 ---- diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst index 56bf273bc..0f2c3bf02 100644 --- a/docs/how-to-use-docs/documentation-guide.rst +++ b/docs/how-to-use-docs/documentation-guide.rst @@ -15,7 +15,7 @@ Getting Started with Documentation for Your Project OPNFV documentation is automated and integrated into our git & gerrit toolchains. We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact -store, our WiKi is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation +store, our Wiki is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation process for project information, content and deliverables. Read :ref:`this page <include-documentation>` which elaborates on how documentation is to be included within opnfvdocs. diff --git a/docs/how-to-use-docs/files/build.yaml b/docs/how-to-use-docs/files/build.yaml new file mode 100644 index 000000000..d04ff731b --- /dev/null +++ b/docs/how-to-use-docs/files/build.yaml @@ -0,0 +1,11 @@ +--- +- project: + name: PROJECT + project-name: '{name}' + + project-pattern: '{name}' + rtd-build-url: RTD_BUILD_URL + rtd-token: RTD_TOKEN + + jobs: + - '{project-name}-rtd-jobs' diff --git a/docs/how-to-use-docs/files/conf.py b/docs/how-to-use-docs/files/conf.py new file mode 100644 index 000000000..3c4453e71 --- /dev/null +++ b/docs/how-to-use-docs/files/conf.py @@ -0,0 +1 @@ +from docs_conf.conf import * diff --git a/docs/how-to-use-docs/files/conf.yaml b/docs/how-to-use-docs/files/conf.yaml new file mode 100644 index 000000000..caad28ff4 --- /dev/null +++ b/docs/how-to-use-docs/files/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: opnfv +project: Example diff --git a/docs/how-to-use-docs/files/index b/docs/how-to-use-docs/files/index new file mode 100644 index 000000000..21da2ac4e --- /dev/null +++ b/docs/how-to-use-docs/files/index @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. (c) Open Platform for NFV Project, Inc. and its contributors + +.. _opnfv-project-foo: + +=== +FOO +=== + +.. toctree:: + :numbered: + :maxdepth: 2 + + development + release + testing diff --git a/docs/how-to-use-docs/files/index.rst b/docs/how-to-use-docs/files/index.rst new file mode 100644 index 000000000..0fa6784ab --- /dev/null +++ b/docs/how-to-use-docs/files/index.rst @@ -0,0 +1,18 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. (c) Open Platform for NFV Project, Inc. and its contributors + +.. _<project-name>: + +============== +<project-name> +============== + +.. toctree:: + :numbered: + :maxdepth: 2 + + release/release-notes/index + release/installation/index + release/userguide/index + scenarios/index diff --git a/docs/how-to-use-docs/files/requirements.txt b/docs/how-to-use-docs/files/requirements.txt new file mode 100644 index 000000000..440843584 --- /dev/null +++ b/docs/how-to-use-docs/files/requirements.txt @@ -0,0 +1,5 @@ +lfdocs-conf +sphinx_opnfv_theme +# Uncomment the following line if your project uses Sphinx to document +# HTTP APIs +# sphinxcontrib-httpdomain diff --git a/docs/how-to-use-docs/files/tox.ini b/docs/how-to-use-docs/files/tox.ini new file mode 100644 index 000000000..69aa18937 --- /dev/null +++ b/docs/how-to-use-docs/files/tox.ini @@ -0,0 +1,17 @@ +[tox] +minversion = 1.6 +envlist = + docs, + docs-linkcheck +skipsdist = true + +[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 diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst index 424f47189..c56ff40ce 100644 --- a/docs/how-to-use-docs/index.rst +++ b/docs/how-to-use-docs/index.rst @@ -9,4 +9,5 @@ Documentation Guide documentation-guide include-documentation + local-build-transition addendum diff --git a/docs/how-to-use-docs/local-build-transition.rst b/docs/how-to-use-docs/local-build-transition.rst new file mode 100644 index 000000000..5d2c806d7 --- /dev/null +++ b/docs/how-to-use-docs/local-build-transition.rst @@ -0,0 +1,130 @@ +Submodule Transition +==================== + +Moving away from submodules. + +At the cost of some release-time overhead, there are several benefits +the transition provides projects: + +* Local builds - Projects will be able to build and view there docs + locally, as they would appear on the OPNFV Docs website. +* Reduced build time - Patchset verification will only run against + individual projects docs, not all projects. +* Decoupled build failures - Any error introduced to project's docs + would not break builds for all the other projects + +Steps +----- + +To make the transition the following steps need to be taken across three +repositories: + +* Your project repository (Ex. Fuel) +* The `Releng`_ repository +* The `OPNFV Docs`_ repository + +.. _Releng: https://git.opnfv.org/releng/ +.. _`OPNFV Docs`: https://git.opnfv.org/opnfvdocs/ + +Adding a Local Build +~~~~~~~~~~~~~~~~~~~~ + +In your project repo: + +#. Add the following files: + + *docs/conf.py* + + .. literalinclude:: files/conf.py + + *docs/conf.yaml* + + .. literalinclude:: files/conf.yaml + + *docs/requirements.txt* + + .. literalinclude:: files/requirements.txt + + *tox.ini* + + .. literalinclude:: files/tox.ini + + *.gitignore*:: + + .tox/ + docs/_build/* + + *docs/index.rst* + + If this file doesn't exist, it will need to be created along any other + missing index file for directories (release, development). Any + example of the file's content looks like this: + + .. literalinclude:: files/index.rst + +You can verify the build works by running:: + + tox -e docs + +Creating a CI Job +~~~~~~~~~~~~~~~~~ + +In the releng repository: + +#. Update your project's job file + **jjb/<project>/<projects-jobs.yaml** with the following (taken from `this guide`_): + + .. literalinclude:: files/build.yaml + +You can either send an email_ to helpdesk in order to get a copy of +**RTD_BUILD_URL** and **RTD_TOKEN**, ping *aricg* or *bramwelt* in +*#opnfv-docs* on Freenode, or add *Aric Gardner* or *Trevor Bramwell* to your +patch as a reviewer and they will pass along the token and build URL. + +.. _email: mailto:helpdesk@opnfv.org +.. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project + +Removing the Submodule +~~~~~~~~~~~~~~~~~~~~~~ + +In the opnfvdocs repository: + +#. Add an intersphinx link to the opnfvdocs repo configuration: + + *docs/conf.py* + + .. code-block:: python + + intersphinx_mapping['<project>'] = ('http://opnfv-<project>.readthedocs.io', None) + + If the project exists on ReadTheDocs, and the previous build was + merged in and ran, you can verify the linking is working currectly by + finding the following line in the output of **tox -e docs**:: + + loading intersphinx inventory from https://opnfv-<project>.readthedocs.io/en/latest/objects.inv... + +#. Ensure all references in opnfvdocs are using **:ref:** or **:doc:** and + not directly specifying submodule files with *../submodules/<project>*. + + For example:: + + .. toctree:: + + ../submodules/releng/docs/overview.rst + + Would become:: + + .. toctree:: + + :ref:`Releng Overview <releng:overview>` + + Some more examples can be seen `here`_. + + .. _here: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#cross-reference-external-docs + +#. Remove the submodule from opnfvdocs, replacing *<project>* with your + project and commit the change:: + + git rm docs/submodules/<project> + git commit -s + git review diff --git a/docs/infrastructure/ci.rst b/docs/infrastructure/ci.rst index a6323ef76..97429a505 100644 --- a/docs/infrastructure/ci.rst +++ b/docs/infrastructure/ci.rst @@ -10,5 +10,5 @@ Continuous Integration - CI Please see the details of CI from the chapters below. -- :ref:`CI Overview <ci-overview>` -- :ref:`CI User Guide <ci-user-guide>` +- :ref:`CI Overview <releng:ci-overview>` +- :ref:`CI User Guide <releng:ci-user-guide>` diff --git a/docs/infrastructure/overview.rst b/docs/infrastructure/overview.rst index 1bd792000..3100907ce 100644 --- a/docs/infrastructure/overview.rst +++ b/docs/infrastructure/overview.rst @@ -41,10 +41,7 @@ TBD Software Infrastructure ----------------------- -.. toctree:: - :maxdepth: 1 - - ../submodules/releng/docs/infra/index +- :ref:`releng:software-infrastructure` Security -------- diff --git a/docs/submodules/apex b/docs/submodules/apex -Subproject bd292a3c44dbe385974e4ee41dcb8149558f0be +Subproject 70cade4f8df150281c16e72d9234fa3751f097c diff --git a/docs/submodules/armband b/docs/submodules/armband -Subproject baa15e4501d47adb80b1648d059881bdf57b2a9 +Subproject a880b5c0fe55397b73f0fcf8f8c87d523327099 diff --git a/docs/submodules/auto b/docs/submodules/auto -Subproject e8a692f727896a16c11364f867c5602b89a0218 +Subproject 1a2260efe5d15f95b8fa778a9ee8023121facd7 diff --git a/docs/submodules/availability b/docs/submodules/availability -Subproject c1ee3631b59009ff61450808e2bd33fe1d4b17f +Subproject d0c0673873f9cfd1752f25d58b760bb2bf51a93 diff --git a/docs/submodules/barometer b/docs/submodules/barometer -Subproject ed61877e2ba389ada8c4e60160b43e999f23d60 +Subproject b52c942a4fbfc5023780d23954de953b817c6dc diff --git a/docs/submodules/bottlenecks b/docs/submodules/bottlenecks -Subproject f6ca90e950a3b007b118cad702616267fab9191 +Subproject 4a94df533b4ae139af5e222e29375c19c7ace01 diff --git a/docs/submodules/calipso b/docs/submodules/calipso -Subproject 06b5a7ba28e759e39ad5637c3a84e8a5c9d5717 +Subproject d62a89bda4da3d24f09a20e9ba09c9fe80ffd5d diff --git a/docs/submodules/clover b/docs/submodules/clover -Subproject a611041d138a71a87c12d4734e5d1a780852ecc +Subproject bf2f1c7aa3491f683b1660de68876cf2731f64a diff --git a/docs/submodules/compass4nfv b/docs/submodules/compass4nfv -Subproject e427f1473051e1de8a0298c1b6972fa5f539b82 +Subproject 9b90a43a543b12050ed8673e2dc9f8b0f13eaeb diff --git a/docs/submodules/container4nfv b/docs/submodules/container4nfv -Subproject f83d24da3d410e1c2ce93ed79e390f1cac6c306 +Subproject 3de127959e70d9ec1c97e78af7b3a047a2ed766 diff --git a/docs/submodules/copper b/docs/submodules/copper -Subproject 37434bd4a46f7df1d3e41e9bbe613f3a2827638 +Subproject 2527488ab77d7e4e4471402e657f5b4752fb6e5 diff --git a/docs/submodules/daisy b/docs/submodules/daisy -Subproject afb9b05fc088fdb60168a2dd25dda90b5d3ab2d +Subproject 560eb13d6468f142d6aaaae78f85bc22a6acc7c diff --git a/docs/submodules/doctor b/docs/submodules/doctor -Subproject db301edb5a06109628af0b2e3416751615f1115 +Subproject da25598a6a31abe0579ffed12d1719e5ff75f9a diff --git a/docs/submodules/domino b/docs/submodules/domino -Subproject eb2fbb1315e6489dd159c8227030d035bdeb186 +Subproject 8330eea4474bf90a358c2255b1d0c6403829579 diff --git a/docs/submodules/dovetail b/docs/submodules/dovetail -Subproject 57c30b969c57843f6200ef6614d776954c30515 +Subproject 60f1c35c294d5d94a862db348315f8f3b9f870b diff --git a/docs/submodules/edgecloud b/docs/submodules/edgecloud new file mode 160000 +Subproject a7c184a7f5fedcc39a077e8c37da7e8fa22272b diff --git a/docs/submodules/fds b/docs/submodules/fds -Subproject 7a27dece748d84f7f665bd7b66e3e3567ee735c +Subproject 406d71e14b99b92db10bf6dc7137970baf6324c diff --git a/docs/submodules/fuel b/docs/submodules/fuel -Subproject 5ab2540591ad029b5b6cf23eab88959fbd14712 +Subproject 27ed4796ac54da3c598929c1aeaed62ba14a533 diff --git a/docs/submodules/functest b/docs/submodules/functest -Subproject f7b6a9a8d69313bbb8203eaf25b2d78d86ae799 +Subproject 9b941ea58c60827d563d266f7dedd0d95de3ca9 diff --git a/docs/submodules/ipv6 b/docs/submodules/ipv6 -Subproject 4730a2a6729fa20c2e5ed39db2e6cf87c67f77d +Subproject 6deace1abcae9479868bf99f527f839da825b26 diff --git a/docs/submodules/moon b/docs/submodules/moon -Subproject d28f8e68ac176a15dbbd7873f757f5a9f221d11 +Subproject 2dbe655587ca98b67c1a3e3798c63fd47229adc diff --git a/docs/submodules/nfvbench b/docs/submodules/nfvbench -Subproject eef8ece12a26773ae2459d36225018430ef00ed +Subproject 59db88a0554459514e40fd512e3d105820a9086 diff --git a/docs/submodules/ovn4nfv b/docs/submodules/ovn4nfv -Subproject e0963ba77b7a4c01215a672e5f3606751912065 +Subproject ba638f983a4247e8bcf53e590b5e39e5016d627 diff --git a/docs/submodules/parser b/docs/submodules/parser -Subproject 320ca9e335797f2081f253df60a860e72b6cc9f +Subproject 26fc7a76a06c83eae2a75a262953b3d8d9bb00b diff --git a/docs/submodules/pharos b/docs/submodules/pharos -Subproject 753797d22d437296ee6f4355ec088e69817e2b4 +Subproject 738497a53b80e3b770457b4160532274fd92438 diff --git a/docs/submodules/promise b/docs/submodules/promise -Subproject 7c28b66a376d8a441c40c2926b218497d63516a +Subproject 2b4a1f6c89a55c4003ecf6d7b9d58c801defad4 diff --git a/docs/submodules/releng b/docs/submodules/releng deleted file mode 160000 -Subproject 554f2b6b58f720960dadea8de57260b8944fba2 diff --git a/docs/submodules/releng-xci b/docs/submodules/releng-xci -Subproject 246029cfa3b70cb3e5678a41187b214620f6d50 +Subproject 84e736bed99882021d5aa74f84ac185bef2bcc8 diff --git a/docs/submodules/samplevnf b/docs/submodules/samplevnf -Subproject b18290d21a28cabbb8b7a31b9c54b7c30e62ec1 +Subproject 3afd384b7e68a3cd29f4d2cdf39785f8441d0b6 diff --git a/docs/submodules/sdnvpn b/docs/submodules/sdnvpn -Subproject 96d17e018f0b4b4547689a31fb0e4f4af1d65a0 +Subproject 64a5e7dc89be1c52253a48fb5ccfa045b6619d0 diff --git a/docs/submodules/sfc b/docs/submodules/sfc -Subproject fc2b3139c7629a601f1a716aea7e65ec4b5fd41 +Subproject 0ed4e451447fb62b642a5b72430dacc21694221 diff --git a/docs/submodules/snaps b/docs/submodules/snaps -Subproject f17b5d4631682b4807dc1c4267da65258413ef7 +Subproject 0dacfaa2fbd2dfe7fc9d438b9350a0187506e61 diff --git a/docs/submodules/stor4nfv b/docs/submodules/stor4nfv -Subproject 63ff6c6ec9ebbca90ac7304a27c0430dbcecb74 +Subproject d65e22d27ab305d38059046dae60d7a66ff4a4e diff --git a/docs/submodules/storperf b/docs/submodules/storperf -Subproject 90f1e7e3a5609035487e59bb6196cd7eb2313ae +Subproject 5f84c19c4511da6706a501308b509aacbc6219d diff --git a/docs/submodules/vswitchperf b/docs/submodules/vswitchperf -Subproject 3daf5942e2ede8088898a9589d41b797e27b6d4 +Subproject 01724ca5eb6198cd0d9bf804e1c7972b2b1edf0 diff --git a/docs/submodules/yardstick b/docs/submodules/yardstick -Subproject f52ffab5e25a768a180644ecfe82caabb54df9a +Subproject e625e162c2e4f817f1bc6a440d85b3cc59272ac diff --git a/docs/testing/testing-dev.rst b/docs/testing/testing-dev.rst index fdefb568e..291781455 100644 --- a/docs/testing/testing-dev.rst +++ b/docs/testing/testing-dev.rst @@ -22,6 +22,13 @@ Bottlenecks ../submodules/bottlenecks/docs/testing/developer/devguide/index +Dovetail / OPNFV Verified Program +--------------------------------- +.. toctree:: + :maxdepth: 1 + + ../submodules/dovetail/docs/testing/developer/testcaserequirements/index + Functest --------- .. toctree:: diff --git a/docs/testing/testing-user.rst b/docs/testing/testing-user.rst index ca1b1c263..ade27a634 100644 --- a/docs/testing/testing-user.rst +++ b/docs/testing/testing-user.rst @@ -19,6 +19,18 @@ Bottlenecks ../submodules/bottlenecks/docs/testing/user/userguide/index +Dovetail / OPNFV Verified Program +--------------------------------- +.. toctree:: + :maxdepth: 1 + + ../submodules/dovetail/docs/testing/user/certificationworkflow/index + ../submodules/dovetail/docs/testing/user/ovpaddendum/index + ../submodules/dovetail/docs/testing/user/reviewerguide/index + ../submodules/dovetail/docs/testing/user/systempreparation/index + ../submodules/dovetail/docs/testing/user/testspecification/index + ../submodules/dovetail/docs/testing/user/userguide/index + Functest --------- .. toctree:: |