blob: 5d2c806d733a74ffd2c5514580f84dde0644e940 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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
|
