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.