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.
129 Testing: Build Documentation Locally
130 ---------------------------------------
132 Composite OPNFVDOCS documentation
133 +++++++++++++++++++++++++++++++++++
134 To build whole documentation under opnfvdocs/, follow these steps:
136 Install virtual environment.
140 sudo pip install virtualenv
141 cd /local/repo/path/to/project
143 Download the OPNFVDOCS repository.
147 git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
149 Change directory to opnfvdocs & install requirements.
154 sudo pip install -r etc/requirements.txt
156 Update submodules, build documentation using tox & then open using any browser.
161 git submodule update --init
163 firefox docs/_build/html/index.html
165 .. note:: Make sure to run `tox -edocs` and not just `tox`.
167 Individual project documentation
168 +++++++++++++++++++++++++++++++++++
169 To test how the documentation renders in HTML, follow these steps:
171 Install virtual environment.
175 sudo pip install virtualenv
176 cd /local/repo/path/to/project
178 Download the opnfvdocs repository.
182 git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
184 Change directory to opnfvdocs & install requirements.
189 sudo pip install -r etc/requirements.txt
191 Move the conf.py file to your project folder where RST files have been kept:
195 mv opnfvdocs/docs/conf.py <path-to-your-folder>/
197 Move the static files to your project folder:
201 mv opnfvdocs/_static/ <path-to-your-folder>/
203 Build the documentation from within your project folder:
207 sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
209 Your documentation shall be built as HTML inside the
210 specified output folder directory.