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 'doc8' Validation
 130 -----------------
 131 It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
 132 To validate your rst files using doc8, install doc8.
 133
 134 .. code-block:: bash
 135
 136    sudo pip install doc8
 137
 138 doc8 can now be used to check the rst files. Execute as,
 139
 140 .. code-block:: bash
 141
 142    doc8 --ignore D000,D001 <file>
 143
 144
 145 Testing: Build Documentation Locally
 146 ------------------------------------
 147
 148 Composite OPNFVDOCS documentation
 149 +++++++++++++++++++++++++++++++++
 150 To build whole documentation under opnfvdocs/, follow these steps:
 151
 152 Install virtual environment.
 153
 154 .. code-block:: bash
 155
 156    sudo pip install virtualenv
 157    cd /local/repo/path/to/project
 158
 159 Download the OPNFVDOCS repository.
 160
 161 .. code-block:: bash
 162
 163    git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
 164
 165 Change directory to opnfvdocs & install requirements.
 166
 167 .. code-block:: bash
 168
 169    cd opnfvdocs
 170    sudo pip install -r etc/requirements.txt
 171
 172 Update submodules, build documentation using tox & then open using any browser.
 173
 174 .. code-block:: bash
 175
 176    cd opnfvdocs
 177    git submodule update --init
 178    tox -edocs
 179    firefox docs/_build/html/index.html
 180
 181 .. note:: Make sure to run `tox -edocs` and not just `tox`.
 182
 183 Individual project documentation
 184 ++++++++++++++++++++++++++++++++
 185 To test how the documentation renders in HTML, follow these steps:
 186
 187 Install virtual environment.
 188
 189 .. code-block:: bash
 190
 191    sudo pip install virtualenv
 192    cd /local/repo/path/to/project
 193
 194 Download the opnfvdocs repository.
 195
 196 .. code-block:: bash
 197
 198    git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
 199
 200 Change directory to opnfvdocs & install requirements.
 201
 202 .. code-block:: bash
 203
 204    cd opnfvdocs
 205    sudo pip install -r etc/requirements.txt
 206
 207 Move the conf.py file to your project folder where RST files have been kept:
 208
 209 .. code-block:: bash
 210
 211    mv opnfvdocs/docs/conf.py <path-to-your-folder>/
 212
 213 Move the static files to your project folder:
 214
 215 .. code-block:: bash
 216
 217    mv opnfvdocs/_static/ <path-to-your-folder>/
 218
 219 Build the documentation from within your project folder:
 220
 221 .. code-block:: bash
 222
 223    sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
 224
 225 Your documentation shall be built as HTML inside the
 226 specified output folder directory.
 227
 228 .. 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.
 229
 230
 231 Adding your project repository as a submodule
 232 --------------------------
 233
 234 Clone the opnfvdocs repository and your submodule to .gitmodules following the convention of the file
 235
 236 .. code-block:: bash
 237
 238   cd docs/submodules/
 239   git submodule git https://gerrit.opnfv.org/gerrit/$reponame
 240   git submodule init $reponame/
 241   git submodule update $reponame/
 242   git add .
 243   git review