1 .. _include-documentation:
2 ============================
3 Including your Documentation
4 ============================
10 In your project repository
11 --------------------------
13 Add your documentation to your repository in the folder structure and
14 according to the templates listed above. The documentation templates you
15 will require are available in opnfvdocs/docs/templates/ repository, you should
16 copy the relevant templates to your <repo>/docs/ directory in your repository.
17 For instance if you want to document userguide, then your steps shall be
22 git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git
23 cp -p opnfvdocs/docs/userguide/* <my_repo>/docs/userguide/
26 You should then add the relevant information to the template that will
27 explain the documentation. When you are done writing, you can commit
28 the documentation to the project repository.
33 git commit --signoff --all
36 In OPNFVDocs Composite Documentation
37 ------------------------------------
42 To import project documents from project repositories, we use submodules.
43 Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows:
45 .. image:: Submodules.jpg
48 To include your project specific documentation in the composite documentation,
49 first identify where your project documentation should be included.
50 Say your project userguide should figure in the ‘OPNFV Userguide’, then:
55 vim opnfvdocs/docs/release/userguide.introduction.rst
57 This opens the text editor. Identify where you want to add the userguide.
58 If the userguide is to be added to the toctree, simply include the path to
67 submodules/functest/docs/userguide/index
68 submodules/bottlenecks/docs/userguide/index
69 submodules/yardstick/docs/userguide/index
70 <submodules/path-to-your-file>
75 It's pretty common to want to reference another location in the
76 OPNFV documentation and it's pretty easy to do with
77 reStructuredText. This is a quick primer, more information is in the
78 `Sphinx section on Cross-referencing arbitrary locations
79 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
81 Within a single document, you can reference another section simply by::
83 This is a reference to `The title of a section`_
85 Assuming that somewhere else in the same file there a is a section
86 title something like::
88 The title of a section
89 ^^^^^^^^^^^^^^^^^^^^^^
91 It's typically better to use ``:ref:`` syntax and labels to provide
92 links as they work across files and are resilient to sections being
93 renamed. First, you need to create a label something like::
97 The title of a section
98 ^^^^^^^^^^^^^^^^^^^^^^
100 .. note:: The underscore (_) before the label is required.
102 Then you can reference the section anywhere by simply doing::
104 This is a reference to :ref:`a-label`
108 This is a reference to :ref:`a section I really liked <a-label>`
110 .. note:: When using ``:ref:``-style links, you don't need a trailing
113 Because the labels have to be unique, it usually makes sense to prefix
114 the labels with the project name to help share the label space, e.g.,
115 ``sfc-user-guide`` instead of just ``user-guide``.
117 Once you have made these changes you need to push the patch back to
118 the opnfvdocs team for review and integration.
123 git commit --signoff --all
126 Be sure to add the project leader of the opnfvdocs project
127 as a reviewer of the change you just pushed in gerrit.
131 It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
132 To validate your rst files using doc8, install doc8.
136 sudo pip install doc8
138 doc8 can now be used to check the rst files. Execute as,
142 doc8 --ignore D000,D001 <file>
145 Testing: Build Documentation Locally
146 ------------------------------------
148 Composite OPNFVDOCS documentation
149 +++++++++++++++++++++++++++++++++
150 To build whole documentation under opnfvdocs/, follow these steps:
152 Install virtual environment.
156 sudo pip install virtualenv
157 cd /local/repo/path/to/project
159 Download the OPNFVDOCS repository.
163 git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
165 Change directory to opnfvdocs & install requirements.
170 sudo pip install -r etc/requirements.txt
172 Update submodules, build documentation using tox & then open using any browser.
177 git submodule update --init
179 firefox docs/_build/html/index.html
181 .. note:: Make sure to run `tox -edocs` and not just `tox`.
183 Individual project documentation
184 ++++++++++++++++++++++++++++++++
185 To test how the documentation renders in HTML, follow these steps:
187 Install virtual environment.
191 sudo pip install virtualenv
192 cd /local/repo/path/to/project
194 Download the opnfvdocs repository.
198 git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
200 Change directory to opnfvdocs & install requirements.
205 sudo pip install -r etc/requirements.txt
207 Move the conf.py file to your project folder where RST files have been kept:
211 mv opnfvdocs/docs/conf.py <path-to-your-folder>/
213 Move the static files to your project folder:
217 mv opnfvdocs/_static/ <path-to-your-folder>/
219 Build the documentation from within your project folder:
223 sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
225 Your documentation shall be built as HTML inside the
226 specified output folder directory.
228 .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
231 Adding your project repository as a submodule
232 --------------------------
234 Clone the opnfvdocs repository and your submodule to .gitmodules following the convention of the file
239 git submodule add https://gerrit.opnfv.org/gerrit/$reponame
240 git submodule init $reponame/
241 git submodule update $reponame/
246 Removing a project repository as a submodule
247 --------------------------
248 git rm docs/submodules/$reponame
249 rm -rf .git/modules/$reponame
250 git config -f .git/config --remove-section submodule.$reponame 2> /dev/null