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

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