docs/how-to-use-docs/include-documentation.rst

   1 .. _include-documentation:
   2 =============================================
   3 Including your Documentation
   4 =============================================
   5
   6 .. contents::
   7    :depth: 3
   8    :local:
   9
  10 In your project repository
  11 ----------------------------
  12
  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
  18 as follows:
  19
  20 .. code-block:: bash
  21
  22    git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git
  23    cp -p opnfvdocs/docs/userguide/* <my_repo>/docs/userguide/
  24
  25
  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.
  29
  30 .. code-block:: bash
  31
  32    git add .
  33    git commit --signoff --all
  34    git review
  35
  36 In OPNFVDocs Composite Documentation
  37 --------------------------------------
  38
  39 In toctree
  40 +++++++++++
  41
  42 To import project documents from project repositories, we use submodules.
  43  Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows:
  44
  45 .. image:: Submodules.jpg
  46    :scale: 50 %
  47
  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:
  51
  52
  53 .. code-block:: bash
  54
  55    vim opnfvdocs/docs/release/userguide.introduction.rst
  56
  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
  59 it, example:
  60
  61
  62 .. code-block:: bash
  63
  64    .. toctree::
  65        :maxdepth: 1
  66
  67     submodules/functest/docs/userguide/index
  68     submodules/bottlenecks/docs/userguide/index
  69     submodules/yardstick/docs/userguide/index
  70     <submodules/path-to-your-file>
  71
  72 As Hyperlink
  73 +++++++++++++
  74
  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>`_.
  80
  81 Within a single document, you can reference another section simply by::
  82
  83    This is a reference to `The title of a section`_
  84
  85 Assuming that somewhere else in the same file there a is a section
  86 title something like::
  87
  88    The title of a section
  89    ^^^^^^^^^^^^^^^^^^^^^^
  90
  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::
  94
  95    .. _a-label:
  96
  97    The title of a section
  98    ^^^^^^^^^^^^^^^^^^^^^^
  99
 100 .. note:: The underscore (_) before the label is required.
 101
 102 Then you can reference the section anywhere by simply doing::
 103
 104     This is a reference to :ref:`a-label`
 105
 106 or::
 107
 108     This is a reference to :ref:`a section I really liked <a-label>`
 109
 110 .. note:: When using ``:ref:``-style links, you don't need a trailing
 111           underscore (_).
 112
 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``.
 116
 117 Once you have made these changes you need to push the patch back to
 118 the opnfvdocs team for review and integration.
 119
 120 .. code-block:: bash
 121
 122    git add .
 123    git commit --signoff --all
 124    git review
 125
 126 Be sure to add the project leader of the opnfvdocs project
 127 as a reviewer of the change you just pushed in gerrit.
 128
 129 Testing: Build Documentation Locally
 130 ---------------------------------------
 131
 132 Composite OPNFVDOCS documentation
 133 +++++++++++++++++++++++++++++++++++
 134 To build whole documentation under opnfvdocs/, follow these steps:
 135
 136 Install virtual environment.
 137
 138 .. code-block:: bash
 139
 140    sudo pip install virtualenv
 141    cd /local/repo/path/to/project
 142
 143 Download the OPNFVDOCS repository.
 144
 145 .. code-block:: bash
 146
 147    git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
 148
 149 Change directory to opnfvdocs & install requirements.
 150
 151 .. code-block:: bash
 152
 153    cd opnfvdocs
 154    sudo pip install -r etc/requirements.txt
 155
 156 Update submodules, build documentation using tox & then open using any browser.
 157
 158 .. code-block:: bash
 159
 160    cd opnfvdocs
 161    git submodule update --init
 162    tox -edocs
 163    firefox docs/_build/html/index.html
 164
 165 .. note:: Make sure to run `tox -edocs` and not just `tox`.
 166
 167 Individual project documentation
 168 +++++++++++++++++++++++++++++++++++
 169 To test how the documentation renders in HTML, follow these steps:
 170
 171 Install virtual environment.
 172
 173 .. code-block:: bash
 174
 175    sudo pip install virtualenv
 176    cd /local/repo/path/to/project
 177
 178 Download the opnfvdocs repository.
 179
 180 .. code-block:: bash
 181
 182    git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
 183
 184 Change directory to opnfvdocs & install requirements.
 185
 186 .. code-block:: bash
 187
 188    cd opnfvdocs
 189    sudo pip install -r etc/requirements.txt
 190
 191 Move the conf.py file to your project folder where RST files have been kept:
 192
 193 .. code-block:: bash
 194
 195    mv opnfvdocs/docs/conf.py <path-to-your-folder>/
 196
 197 Move the static files to your project folder:
 198
 199 .. code-block:: bash
 200
 201    mv opnfvdocs/_static/ <path-to-your-folder>/
 202
 203 Build the documentation from within your project folder:
 204
 205 .. code-block:: bash
 206
 207    sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
 208
 209 Your documentation shall be built as HTML inside the
 210 specified output folder directory.