blob: 3697edf7e73a33622dcd0c1733f9e20f84b4a0cb (
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
|
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/
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
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
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
|
