diff options
Diffstat (limited to 'docs/how-to-use-docs')
| -rw-r--r-- | docs/how-to-use-docs/documentation-guide.rst | 2 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/build.yaml | 11 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/conf.py | 1 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/conf.yaml | 3 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/index | 17 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/index.rst | 18 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/requirements.txt | 5 | ||||
| -rw-r--r-- | docs/how-to-use-docs/files/tox.ini | 17 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/how-to-use-docs/local-build-transition.rst | 130 |
10 files changed, 204 insertions, 1 deletions
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 |