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 In toctree
  41 +++++++++++
  42
  43 To import project documents from project repositories, we use submodules.
  44  Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows:
  45
  46 .. image:: Submodules.jpg
  47    :scale: 50 %
  48
  49 To include your project specific documentation in the composite documentation,
  50 first identify where your project documentation should be included.
  51 Say your project userguide should figure in the ‘OPNFV Userguide’, then:
  52
  53
  54 .. code-block:: bash
  55
  56    vim opnfvdocs/docs/release/userguide.introduction.rst
  57
  58 This opens the text editor. Identify where you want to add the userguide.
  59 If the userguide is to be added to the toctree, simply include the path to
  60 it, example:
  61
  62
  63 .. code-block:: bash
  64
  65    .. toctree::
  66        :maxdepth: 1
  67
  68     submodules/functest/docs/userguide/index
  69     submodules/bottlenecks/docs/userguide/index
  70     submodules/yardstick/docs/userguide/index
  71     <submodules/path-to-your-file>
  72
  73 As Hyperlink
  74 ++++++++++++
  75
  76 It's pretty common to want to reference another location in the
  77 OPNFV documentation and it's pretty easy to do with
  78 reStructuredText. This is a quick primer, more information is in the
  79 `Sphinx section on Cross-referencing arbitrary locations
  80 <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_.
  81
  82 Within a single document, you can reference another section simply by::
  83
  84    This is a reference to `The title of a section`_
  85
  86 Assuming that somewhere else in the same file there a is a section
  87 title something like::
  88
  89    The title of a section
  90    ^^^^^^^^^^^^^^^^^^^^^^
  91
  92 It's typically better to use ``:ref:`` syntax and labels to provide
  93 links as they work across files and are resilient to sections being
  94 renamed. First, you need to create a label something like::
  95
  96    .. _a-label:
  97
  98    The title of a section
  99    ^^^^^^^^^^^^^^^^^^^^^^
 100
 101 .. note:: The underscore (_) before the label is required.
 102
 103 Then you can reference the section anywhere by simply doing::
 104
 105     This is a reference to :ref:`a-label`
 106
 107 or::
 108
 109     This is a reference to :ref:`a section I really liked <a-label>`
 110
 111 .. note:: When using ``:ref:``-style links, you don't need a trailing
 112           underscore (_).
 113
 114 Because the labels have to be unique, it usually makes sense to prefix
 115 the labels with the project name to help share the label space, e.g.,
 116 ``sfc-user-guide`` instead of just ``user-guide``.
 117
 118 Once you have made these changes you need to push the patch back to
 119 the opnfvdocs team for review and integration.
 120
 121 .. code-block:: bash
 122
 123    git add .
 124    git commit --signoff --all
 125    git review
 126
 127 Be sure to add the project leader of the opnfvdocs project
 128 as a reviewer of the change you just pushed in gerrit.
 129
 130 'doc8' Validation
 131 -----------------
 132 It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards.
 133 To validate your rst files using doc8, install doc8.
 134
 135 .. code-block:: bash
 136
 137    sudo pip install doc8
 138
 139 doc8 can now be used to check the rst files. Execute as,
 140
 141 .. code-block:: bash
 142
 143    doc8 --ignore D000,D001 <file>
 144
 145
 146 Testing: Build Documentation Locally
 147 ------------------------------------
 148
 149 Composite OPNFVDOCS documentation
 150 +++++++++++++++++++++++++++++++++
 151 To build whole documentation under opnfvdocs/, follow these steps:
 152
 153 Install virtual environment.
 154
 155 .. code-block:: bash
 156
 157    sudo pip install virtualenv
 158    cd /local/repo/path/to/project
 159
 160 Download the OPNFVDOCS repository.
 161
 162 .. code-block:: bash
 163
 164    git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
 165
 166 Change directory to opnfvdocs & install requirements.
 167
 168 .. code-block:: bash
 169
 170    cd opnfvdocs
 171    sudo pip install -r etc/requirements.txt
 172
 173 Update submodules, build documentation using tox & then open using any browser.
 174
 175 .. code-block:: bash
 176
 177    cd opnfvdocs
 178    git submodule update --init
 179    tox -edocs
 180    firefox docs/_build/html/index.html
 181
 182 .. note:: Make sure to run `tox -edocs` and not just `tox`.
 183
 184 Individual project documentation
 185 ++++++++++++++++++++++++++++++++
 186 To test how the documentation renders in HTML, follow these steps:
 187
 188 Install virtual environment.
 189
 190 .. code-block:: bash
 191
 192    sudo pip install virtualenv
 193    cd /local/repo/path/to/project
 194
 195 Download the opnfvdocs repository.
 196
 197 .. code-block:: bash
 198
 199    git clone https://gerrit.opnfv.org/gerrit/opnfvdocs
 200
 201 Change directory to opnfvdocs & install requirements.
 202
 203 .. code-block:: bash
 204
 205    cd opnfvdocs
 206    sudo pip install -r etc/requirements.txt
 207
 208 Move the conf.py file to your project folder where RST files have been kept:
 209
 210 .. code-block:: bash
 211
 212    mv opnfvdocs/docs/conf.py <path-to-your-folder>/
 213
 214 Move the static files to your project folder:
 215
 216 .. code-block:: bash
 217
 218    mv opnfvdocs/_static/ <path-to-your-folder>/
 219
 220 Build the documentation from within your project folder:
 221
 222 .. code-block:: bash
 223
 224    sphinx-build -b html <path-to-your-folder> <path-to-output-folder>
 225
 226 Your documentation shall be built as HTML inside the
 227 specified output folder directory.
 228
 229 .. 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.
 230
 231
 232 Adding your project repository as a submodule
 233 ---------------------------------------------
 234
 235 Clone the opnfvdocs repository and your submodule to .gitmodules following the convention of the file
 236
 237 .. code-block:: bash
 238
 239   cd docs/submodules/
 240   git submodule add https://gerrit.opnfv.org/gerrit/$reponame
 241   git submodule init $reponame/
 242   git submodule update $reponame/
 243   git add .
 244   git commit -sv
 245   git review
 246
 247 Removing a project repository as a submodule
 248 --------------------------------------------
 249
 250 .. code-block:: bash
 251
 252   git rm docs/submodules/$reponame
 253   rm -rf .git/modules/$reponame
 254   git config -f .git/config --remove-section submodule.$reponame 2> /dev/null
 255   git add .
 256   git commit -sv
 257   git review
 258