From 2e9eaa7d68433b0c999e9abd8c59b687f53fb3d2 Mon Sep 17 00:00:00 2001 From: Trevor Bramwell Date: Thu, 6 Sep 2018 16:19:36 -0700 Subject: Update Submodule Transition Guide Adds headers for each section, updates the jobs config needed for projects, adds an example for updating references in opnfvdocs, and clarifies a few changes such as where the intersphinx link should go. Change-Id: I9b1c09bdc5df776e36f0f14bc80d19dd3f8c679e Signed-off-by: Trevor Bramwell --- docs/how-to-use-docs/files/build.yaml | 5 -- docs/how-to-use-docs/local-build-transition.rst | 62 ++++++++++++++++++------- 2 files changed, 45 insertions(+), 22 deletions(-) diff --git a/docs/how-to-use-docs/files/build.yaml b/docs/how-to-use-docs/files/build.yaml index 452655ae5..d04ff731b 100644 --- a/docs/how-to-use-docs/files/build.yaml +++ b/docs/how-to-use-docs/files/build.yaml @@ -3,11 +3,6 @@ name: PROJECT project-name: '{name}' - build-timeout: 60 - build-node: 'opnfv-build' - gerrit-server-name: 'gerrit.opnfv.org' - jenkins-ssh-credential: 'd42411ac011ad6f3dd2e1fa34eaa5d87f910eb2e' - project-pattern: '{name}' rtd-build-url: RTD_BUILD_URL rtd-token: RTD_TOKEN diff --git a/docs/how-to-use-docs/local-build-transition.rst b/docs/how-to-use-docs/local-build-transition.rst index c22951184..c8d196a67 100644 --- a/docs/how-to-use-docs/local-build-transition.rst +++ b/docs/how-to-use-docs/local-build-transition.rst @@ -26,6 +26,9 @@ repositories: .. _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: @@ -59,6 +62,13 @@ In your project repo: .. 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 @@ -74,29 +84,47 @@ 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 a intersphinx link to the opnfvdocs repo: +#. Add an intersphinx link to the opnfvdocs repo configuration: - Here 'example' should be replaced with the name of your project. + *docs/conf.py* .. code-block:: python - :name: docs/conf.py - intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None) + intersphinx_mapping[''] = ('http://opnfv-.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-.readthedocs.io/en/latest/objects.inv... + +#. Ensure all references in opnfvdocs are using **:ref:** or **:doc:** and + not directly specifying submodule files with *../submodules/*. + + For example:: + + .. toctree:: + + ../submodules/releng/docs/overview.rst + + Would become:: + + .. toctree:: + + :ref:`Releng Overview ` + + Some more examples can be seen `here`_. -#. Ensure all references in opnfvdocs are using `:ref:` and not - directly specifying submodule files (No `:doc:` or 'submodules/...' - in `.. toctree:`) + .. _here: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#cross-reference-external-docs -#. Remove the submodule from opnfvdocs:: +#. Remove the submodule from opnfvdocs, replacing ** with your + project and commit the change:: - 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 + git rm docs/submodules/ + git commit -s + git review -- cgit 1.2.3-korg