4 Moving away from submodules.
6 At the cost of some release-time overhead, there are several benefits
7 the transition provides projects:
9 * Local builds - Projects will be able to build and view there docs
10 locally, as they would appear on the OPNFV Docs website.
11 * Reduced build time - Patchset verification will only run against
12 individual projects docs, not all projects.
13 * Decoupled build failures - Any error introduced to project's docs
14 would not break builds for all the other projects
19 To make the transition the following steps need to be taken across three
22 * Your project repository (Ex. Fuel)
23 * The `Releng`_ repository
24 * The `OPNFV Docs`_ repository
26 .. _Releng: https://git.opnfv.org/releng/
27 .. _`OPNFV Docs`: https://git.opnfv.org/opnfvdocs/
34 #. Add the following files:
38 .. literalinclude:: files/conf.py
42 .. literalinclude:: files/conf.yaml
44 *docs/requirements.txt*
46 .. literalinclude:: files/requirements.txt
50 .. literalinclude:: files/tox.ini
59 If this file doesn't exist, it will need to be created along any other
60 missing index file for directories (release, development). Any
61 example of the file's content looks like this:
63 .. literalinclude:: files/index.rst
65 You can verify the build works by running::
72 In the releng repository:
74 #. Update your project's job file
75 **jjb/<project>/<projects-jobs.yaml** with the following (taken from `this guide`_):
77 .. literalinclude:: files/build.yaml
79 You can either send an email_ to helpdesk in order to get a copy of
80 **RTD_BUILD_URL** and **RTD_TOKEN**, ping *aricg* or *bramwelt* in
81 *#opnfv-docs* on Freenode, or add *Aric Gardner* or *Trevor Bramwell* to your
82 patch as a reviewer and they will pass along the token and build URL.
84 .. _email: mailto:helpdesk@opnfv.org
85 .. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
87 Removing the Submodule
88 ~~~~~~~~~~~~~~~~~~~~~~
90 In the opnfvdocs repository:
92 #. Add an intersphinx link to the opnfvdocs repo configuration:
96 .. code-block:: python
98 intersphinx_mapping['<project>'] = ('http://opnfv-<project>.readthedocs.io', None)
100 If the project exists on ReadTheDocs, and the previous build was
101 merged in and ran, you can verify the linking is working currectly by
102 finding the following line in the output of **tox -e docs**::
104 loading intersphinx inventory from https://opnfv-<project>.readthedocs.io/en/latest/objects.inv...
106 #. Ensure all references in opnfvdocs are using **:ref:** or **:doc:** and
107 not directly specifying submodule files with *../submodules/<project>*.
113 ../submodules/releng/docs/overview.rst
119 :ref:`Releng Overview <releng:overview>`
121 Some more examples can be seen `here`_.
123 .. _here: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#cross-reference-external-docs
125 #. Remove the submodule from opnfvdocs, replacing *<project>* with your
126 project and commit the change::
128 git rm docs/submodules/<project>