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 <tbramwell@linuxfoundation.org>
name: PROJECT
project-name: '{name}'
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
project-pattern: '{name}'
rtd-build-url: RTD_BUILD_URL
rtd-token: RTD_TOKEN
.. _Releng: https://git.opnfv.org/releng/
.. _`OPNFV Docs`: https://git.opnfv.org/opnfvdocs/
.. _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:
In your project repo:
#. Add the following files:
.. literalinclude:: files/index.rst
.. 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
In the releng repository:
#. Update your project's job file
.. _email: mailto:helpdesk@opnfv.org
.. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
.. _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:
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.
- intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None)
+ 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`_.
-#. 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 *<project>* 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/<project>
+ git commit -s
+ git review