From: Trevor Bramwell Date: Mon, 4 Jun 2018 12:36:44 +0000 (+0200) Subject: Submodule to RTD transition documentation X-Git-Tag: opnfv-10.0.0~663^2 X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=commitdiff_plain;h=8f28a9846b2ec7470004f3203a1d3b380855726e;p=opnfvdocs.git Submodule to RTD transition documentation Adds documentation for current projects on how to migrate to using local doc builds, along with steps for new projects to setup their builds. Issue: DOCS-191 Change-Id: I1c850457dec1006199d095ad63469af1ca02a760 Signed-off-by: Trevor Bramwell --- 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 ` which elaborates on how documentation is to be included within opnfvdocs. 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/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..415afe816 --- /dev/null +++ b/docs/how-to-use-docs/local-build-transition.rst @@ -0,0 +1,91 @@ +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 the +project repository, releng repository and opnfvdocs repository. + +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 it doesn't exist along with other index file for directories + (release, development) + +In the releng repository: + +#. Follow the steps in `this guide`_ from the Linux Foundation Releng team on + bootstrapping a new ReadTheDocs (RTD) project. + + This will ensure RTD will update each time docs patches are merged to + the repository. + +.. note: In step 4 of the guide, the file this job should be added to is: + **jjb/project/project-jobs.yaml**, where project is the OPNFV project. + +.. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project + + +In the opnfvdocs repository: + +#. Add a intersphinx link to the opnfvdocs repo: + + Here 'example' should be replaced with the name of your project. + + .. code-block:: python + :name: docs/conf.py + + intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None) + +#. Ensure all references in opnfvdocs are using `:ref:` and not + directly specifying submodule files (No `:doc:` or 'submodules/...' + in `.. toctree:`) + +#. Remove the submodule from opnfvdocs:: + + diff --git a/.gitmodules b/.gitmodules + index 846ab245..aab01642 100644 + --- a/.gitmodules + +++ b/.gitmodules + @@ -151,4 +150,0 @@ + -[submodule "docs/submodules/releng"] + - path = docs/submodules/releng + - url = ../releng + - branch = master