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

   1 ==================================================
   2 How to create documentation for your OPNFV project
   3 ==================================================
   4
   5 Directory Structure
   6 ===================
   7
   8 This is the directory structure of the docs/ directory which have to be placed
   9 in the root of your project directory.
  10
  11 .. code-block:: bash
  12
  13     ./how-to-use-docs/documentation-example.rst
  14     ./how-to-use-docs/index.rst
  15
  16 To create your own document, create any number of directories (depending
  17 on your need, e.g. manual) under the docs/ and place an index.rst in each
  18 directories.
  19 The depth of all directory should be one, so that you can make sure that
  20 all directory names are unique. If you want to have set of all documents in
  21 your repo, create new ``docs/all/index.rst`` and list document links in OPNFV
  22 artifact server (artifact.opnfv.org) instead of including all other rst files
  23 or having ``docs/index.rst``, in order to avoid having duplicated contents in
  24 your documents.
  25
  26 Note:
  27 You may have "docs/how-to-use-docs/" in you project repo. You can delete it,
  28 since it is sample and master version is stored in opnfvdocs repo.
  29
  30 Note:
  31 During the document build process, 'docs_build' and 'docs_output' will be
  32 created in the project root directory. To avoid conflict, you should not
  33 use those names and should add the following entries in '.gitignore' file
  34 so that git can ignore built files.
  35
  36 .. code-block:: bash
  37
  38     /docs_build/
  39     /docs_output/
  40
  41 Index File
  42 ==========
  43
  44 This index file must refence your other rst files in that directory.
  45
  46 Here is an example index.rst :
  47
  48 .. code-block:: bash
  49
  50     *******************
  51     Documentation Title
  52     *******************
  53
  54     .. toctree::
  55        :numbered:
  56        :maxdepth: 2
  57
  58        documentation-example.rst
  59
  60 Source Files
  61 ============
  62
  63 Document source files have to be written in reStructuredText format (rst).
  64 Each file would be build as an html page and a chapter in PDF.
  65
  66 Here is an example source rst file :
  67
  68 .. code-block:: bash
  69
  70     =============
  71     Chapter Title
  72     =============
  73
  74     Section Title
  75     =============
  76
  77     Hello!
  78
  79 Writing RST Markdown
  80 ====================
  81
  82 See http://sphinx-doc.org/rest.html .
  83
  84 **Hint:**
  85 Table and its contents won't be adjusted, so you may need to fix your source
  86 text when your table is truncated in PDF version. Or, you can use 'longtable'
  87 option that splits your table vertically (by rows) in multiple pages.
  88 It is useful if you have trouble in rendering table containing many rows.
  89
  90 .. code-block:: bash
  91
  92     .. table::
  93         :class: longtable
  94
  95         +------------------------+------------+----------+----------+
  96         | Header row, column 1   | Header 2   | Header 3 | Header 4 |
  97         +========================+============+==========+==========+
  98         | body row 1, column 1   | column 2   | column 3 | column 4 |
  99         +------------------------+------------+----------+----------+
 100         | body row 2             | ...        | ...      |          |
 101         +------------------------+------------+----------+----------+
 102
 103 **Hint:**
 104 You can add dedicated contents by using 'only' directive with build type
 105 ('html' and 'pdf') for OPNFV document. But, this is not encouraged to use
 106 since this may make different views in HTML and PDF version.
 107
 108 .. code-block:: bash
 109
 110     .. only:: html
 111         This line will be shown only in html version.
 112
 113 Configuration
 114 =============
 115
 116 If you need to change the default configuration for document build, create
 117 new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
 118 that will be used in build process instead of default for OPNFV document
 119 build.
 120 During the build process, the following default parameters are automatically
 121 added if they are not set in the ``conf.py``.
 122
 123 * **extensions** =
 124   ['sphinxcontrib.httpdomain',
 125   'sphinx.ext.autodoc',
 126   'sphinx.ext.viewcode',
 127   'sphinx.ext.napoleon']
 128 * **needs_sphinx** = '1.3'
 129 * **numfig** = True
 130 * **master_doc** = 'index'
 131 * **pygments_style** = 'sphinx'
 132 * **html_use_index** = False
 133 * **html_logo** = 'opnfv-logo.png'
 134 * **latex_domain_indices** = False
 135 * **latex_logo** = 'opnfv-logo.png'
 136 * **latex_documents** =
 137   [('index', '``document directory name``.tex',
 138   '``document title in index.rst``', 'OPNFV', 'manual'),]
 139 * **release** = '``git last tag name`` (``git last commit hash``)'
 140 * **version** = '``git last tag name`` (``git last commit hash``)'
 141 * **project** = '``git repo name``'
 142 * **copyright** = '``year``, OPNFV'
 143 * **rst_epilog** = '    Revision:``git last commit hash``\n    Build date:``build date in year-month-date format``'
 144
 145 **Note:**
 146 You can leave the file path for OPNFV logo image which will be prepared
 147 before each document build.
 148
 149 **Hint:**
 150 In PDF, figures will be floated to get better view. If you want to avoid such
 151 automated fixes, just add this option to your conf.py after copying the default
 152 configuration in to the document directory.
 153
 154 .. code-block:: bash
 155
 156     latex_elements = {'figure_align': 'H'}
 157
 158 Versioning
 159 ==========
 160
 161 The relevant release and version information will be added to your documents
 162 by using tags from your project's git repository.
 163 The tags will be applied by Releng Project.
 164
 165 Testing
 166 =======
 167
 168 You can test document build in your laptop by using build script which is
 169 also used in document build jobs below:
 170
 171 .. code-block:: bash
 172
 173     $ sudo pip install virtualenv
 174     $ cd /local/repo/path/to/project
 175     $ git clone https://git.opnfv.org/opnfvdocs docs_build/_opnfvdocs
 176     $ ./docs_build/_opnfvdocs/scripts/docs-build.sh
 177
 178 Then, you can see the docs in 'docs_output' directory if build succeeded.
 179
 180 If you have a problem of missing python package, you can make sure all
 181 necessary packages are installed as follows:
 182
 183 .. code-block:: bash
 184
 185     $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
 186
 187 Note:
 188 Developers are encouraged to use
 189 "ssh://<username>@gerrit.opnfv.org:29418/opnfvdocs"
 190 instead of "https://git.opnfv.org/opnfvdocs", so that you can quickly start
 191 development in opnfvdocs.
 192 See https://wiki.opnfv.org/display/DEV/Developer+Getting+Started for more detail.
 193
 194
 195 Jenkins Jobs
 196 ============
 197
 198 Enabling Jenkins Jobs
 199 ---------------------
 200
 201 Jenkins in OPNFV infra performs the jobs to verify and update your documents.
 202 To make your project repository watched by Jenkins to execute those jobs, you
 203 have to add your project name in 'project-pattern' of the following jobs by
 204 sending patch to update `jjb/opnfv/opnfv-docs.yml`_ on gerrit.
 205
 206 .. _jjb/opnfv/opnfv-docs.yml:
 207     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/opnfv/opnfv-docs.yml;
 208
 209 Verify Job
 210 ----------
 211
 212 The verify job name is **opnfv-docs-verify**.
 213
 214 When you send document changes to gerrit, jenkins will create your documents
 215 in HTML and PDF formats to verify that new document can be built successfully.
 216 Please check the jenkins log and artifact carefully.
 217 You can improve your document even though if the build job succeeded.
 218
 219 Documents will be uploaded to
 220 ``http://artifacts.opnfv.org/review/<Change Number>/`` for review.
 221 Those documents will be replaced if you update the change by sending new
 222 patch set to gerrit, and deleted after the change is merged.
 223 Document link(s) can be found in your change page on gerrit as a review
 224 comment.
 225
 226 Note:
 227 Currently, the job reports 'SUCCESS' as result of document build even if the
 228 PDF creation failed. This is a provisional workaround, since many projects are
 229 not ready for PDF creation yet.
 230
 231 Merge Job
 232 ----------
 233
 234 The merge job name is **opnfv-docs-merge**.
 235
 236 Once you are happy with the look of your documentation, you can submit the
 237 change. Then, the merge job will upload latest build documents to
 238 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
 239 You can put links in your project wiki page, so that everyone can see the
 240 latest document always.
 241
 242 Sphinx Extensions
 243 =================
 244
 245 You can see available sphinx extension(s) in `opnfvdocs/etc/requirements.txt`_.
 246
 247 .. _opnfvdocs/etc/requirements.txt:
 248     https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=etc/requirements.txt;
 249
 250 You can use other sphinx extensions to improve your documents.
 251 To share such improvements, we encourage you to enable the extension in OPNFV infra
 252 by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
 253 (proposing change in `opnfvdocs/scripts/docs-build.sh`_ and `opnfvdocs/etc/requirements.txt`_).
 254 After quick sanity checks, we'll merge the patch to make it available in OPNFV
 255 document build.
 256
 257 .. _opnfvdocs/scripts/docs-build.sh:
 258     https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=scripts/docs-build.sh;
 259
 260 Hooks
 261 =====
 262
 263 The document builder script supports pre-hook. If you need to execute some
 264 commands before starting to build process (e.g. generate API rst from codes),
 265 create '<your repo>/docs/pre-hook.sh' which will be executed (using 'source')
 266 once before all document build start.