1 .. _include-documentation:
3 ============================
4 Including your Documentation
5 ============================
11 In your project repository
12 --------------------------
14 Add your documentation to your repository in the folder structure and
15 according to the templates listed above. The documentation templates you
16 will require are available in opnfvdocs/docs/templates/ repository, you should
17 copy the relevant templates to your <repo>/docs/ directory in your repository.
18 For instance if you want to document userguide, then your steps shall be
23 git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git
24 cp -p opnfvdocs/docs/userguide/* <my_repo>/docs/userguide/
27 You should then add the relevant information to the template that will
28 explain the documentation. When you are done writing, you can commit
29 the documentation to the project repository.
34 git commit --signoff --all
37 In OPNFVDocs Composite Documentation
38 ------------------------------------
40 To include your project specific documentation in the composite documentation,
41 first identify where your project documentation should be included.
42 Say your project userguide should figure in the ‘OPNFV Userguide’, then:
47 vim opnfvdocs/docs/release/userguide.introduction.rst
49 This opens the text editor. Identify where you want to add the userguide.
50 If the userguide is to be added to the toctree, simply include the path to
59 submodules/functest/docs/userguide/index
60 submodules/bottlenecks/docs/userguide/index
61 submodules/yardstick/docs/userguide/index
62 <submodules/path-to-your-file>
67 It's pretty common to want to reference another location in the
68 OPNFV documentation and it's pretty easy to do with
69 reStructuredText. This is a quick primer, more information is in the
70 `Sphinx section on Cross-referencing arbitrary locations
71 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
73 Within a single document, you can reference another section simply by::
75 This is a reference to `The title of a section`_
77 Assuming that somewhere else in the same file there a is a section
78 title something like::
80 The title of a section
81 ^^^^^^^^^^^^^^^^^^^^^^
83 It's typically better to use ``:ref:`` syntax and labels to provide
84 links as they work across files and are resilient to sections being
85 renamed. First, you need to create a label something like::
89 The title of a section
90 ^^^^^^^^^^^^^^^^^^^^^^
92 .. note:: The underscore (_) before the label is required.
94 Then you can reference the section anywhere by simply doing::
96 This is a reference to :ref:`a-label`
100 This is a reference to :ref:`a section I really liked <a-label>`
102 .. note:: When using ``:ref:``-style links, you don't need a trailing
105 Because the labels have to be unique, it usually makes sense to prefix
106 the labels with the project name to help share the label space, e.g.,
107 ``sfc-user-guide`` instead of just ``user-guide``.
109 Once you have made these changes you need to push the patch back to
110 the opnfvdocs team for review and integration.
115 git commit --signoff --all
118 Be sure to add the project leader of the opnfvdocs project
119 as a reviewer of the change you just pushed in gerrit.
123 It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
124 To validate your rst files using doc8, install doc8.
128 sudo pip install doc8
130 doc8 can now be used to check the rst files. Execute as,
134 doc8 --ignore D000,D001 <file>
137 Testing: Build Documentation Locally
138 ------------------------------------
140 Composite OPNFVDOCS documentation
141 +++++++++++++++++++++++++++++++++
142 To build whole documentation under opnfvdocs/, follow these steps:
144 Install virtual environment.
148 sudo pip install virtualenv
149 cd /local/repo/path/to/project
151 Download the OPNFVDOCS repository.
155 git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
157 Change directory to opnfvdocs & install requirements.
162 sudo pip install -r etc/requirements.txt
164 Update submodules, build documentation using tox & then open using any browser.
169 git submodule update --init
171 firefox docs/_build/html/index.html
173 .. note:: Make sure to run `tox -edocs` and not just `tox`.
175 Individual project documentation
176 ++++++++++++++++++++++++++++++++
177 To test how the documentation renders in HTML, follow these steps:
179 Install virtual environment.
183 sudo pip install virtualenv
184 cd /local/repo/path/to/project
186 Download the opnfvdocs repository.
190 git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
192 Change directory to opnfvdocs & install requirements.
197 sudo pip install -r etc/requirements.txt
199 Move the conf.py file to your project folder where RST files have been kept:
203 mv opnfvdocs/docs/conf.py <path-to-your-folder>/
205 Move the static files to your project folder:
209 mv opnfvdocs/_static/ <path-to-your-folder>/
211 Build the documentation from within your project folder:
215 sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
217 Your documentation shall be built as HTML inside the
218 specified output folder directory.
220 .. 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.