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.
  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 You can add dedicated contents by using 'only' directive with build type
  86 ('html' and 'singlehtml') for OPNFV document. But, this is not encouraged to
  87 use since this may make different views.
  88
  89 .. code-block:: bash
  90
  91     .. only:: html
  92         This line will be shown only in html version.
  93
  94 Configuration
  95 =============
  96
  97 If you need to change the default configuration for document build, create
  98 new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
  99 that will be used in build process instead of default for OPNFV document
 100 build.
 101 During the build process, the following default parameters are automatically
 102 added if they are not set in the ``conf.py``.
 103
 104 * **extensions** =
 105   ['sphinxcontrib.httpdomain',
 106   'sphinx.ext.autodoc',
 107   'sphinx.ext.viewcode',
 108   'sphinx.ext.napoleon']
 109 * **needs_sphinx** = '1.3'
 110 * **numfig** = True
 111 * **master_doc** = 'index'
 112 * **pygments_style** = 'sphinx'
 113 * **html_use_index** = False
 114 * **html_logo** = 'opnfv-logo.png'
 115 * **html_sidebars** = {'**': ['globaltoc.html',
 116   '``path to opnfvdocs dir``/etc/pagemenu.html',
 117   'searchbox.html']}
 118 * **release** = '``git last tag name`` (``git last commit hash``)'
 119 * **version** = '``git last tag name`` (``git last commit hash``)'
 120 * **project** = '``git repo name``'
 121 * **copyright** = '``year``, OPNFV'
 122 * **rst_epilog** = '    Revision:``git last commit hash``\n    Build date:``build date in year-month-date format``'
 123
 124 **Note:**
 125 You can leave the file path for OPNFV logo image which will be prepared
 126 before each document build.
 127
 128 Versioning
 129 ==========
 130
 131 The relevant release and version information will be added to your documents
 132 by using tags from your project's git repository.
 133 The tags will be applied by Releng Project.
 134
 135 Testing
 136 =======
 137
 138 You can test document build in your laptop by using build script which is
 139 also used in document build jobs below:
 140
 141 .. code-block:: bash
 142
 143     $ sudo pip install virtualenv
 144     $ cd /local/repo/path/to/project
 145     $ git clone https://git.opnfv.org/opnfvdocs docs_build/_opnfvdocs
 146     $ ./docs_build/_opnfvdocs/scripts/docs-build.sh
 147
 148 Then, you can see the docs in 'docs_output' directory if build succeeded.
 149
 150 If you have a problem of missing python package, you can make sure all
 151 necessary packages are installed as follows:
 152
 153 .. code-block:: bash
 154
 155     $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
 156
 157 Note:
 158 Developers are encouraged to use
 159 "ssh://<username>@gerrit.opnfv.org:29418/opnfvdocs"
 160 instead of "https://git.opnfv.org/opnfvdocs", so that you can quickly start
 161 development in opnfvdocs.
 162 See https://wiki.opnfv.org/display/DEV/Developer+Getting+Started for more detail.
 163
 164
 165 Jenkins Jobs
 166 ============
 167
 168 Enabling Jenkins Jobs
 169 ---------------------
 170
 171 Jenkins in OPNFV infra performs the jobs to verify and update your documents.
 172 To make your project repository watched by Jenkins to execute those jobs, you
 173 have to add your project name in 'project-pattern' of the following jobs by
 174 sending patch to update `jjb/opnfv/opnfv-docs.yml`_ on gerrit.
 175
 176 .. _jjb/opnfv/opnfv-docs.yml:
 177     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/opnfv/opnfv-docs.yml;
 178
 179 Verify Job
 180 ----------
 181
 182 The verify job name is **opnfv-docs-verify**.
 183
 184 When you send document changes to gerrit, jenkins will create your documents
 185 in HTML formats (normal and single-page) to verify that new document can be
 186 built successfully. Please check the jenkins log and artifact carefully.
 187 You can improve your document even though if the build job succeeded.
 188
 189 Documents will be uploaded to
 190 ``http://artifacts.opnfv.org/review/<Change Number>/`` for review.
 191 Those documents will be replaced if you update the change by sending new
 192 patch set to gerrit, and deleted after the change is merged.
 193 Document link(s) can be found in your change page on gerrit as a review
 194 comment.
 195
 196 Merge Job
 197 ----------
 198
 199 The merge job name is **opnfv-docs-merge**.
 200
 201 Once you are happy with the look of your documentation, you can submit the
 202 change. Then, the merge job will upload latest build documents to
 203 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
 204 You can put links in your project wiki page, so that everyone can see the
 205 latest document always.
 206
 207 Sphinx Extensions
 208 =================
 209
 210 You can see available sphinx extension(s) in `opnfvdocs/etc/requirements.txt`_.
 211
 212 .. _opnfvdocs/etc/requirements.txt:
 213     https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=etc/requirements.txt;
 214
 215 You can use other sphinx extensions to improve your documents.
 216 To share such improvements, we encourage you to enable the extension in OPNFV infra
 217 by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
 218 (proposing change in `opnfvdocs/scripts/docs-build.sh`_ and `opnfvdocs/etc/requirements.txt`_).
 219 After quick sanity checks, we'll merge the patch to make it available in OPNFV
 220 document build.
 221
 222 .. _opnfvdocs/scripts/docs-build.sh:
 223     https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=scripts/docs-build.sh;
 224
 225 Hooks
 226 =====
 227
 228 The document builder script supports pre-hook. If you need to execute some
 229 commands before starting to build process (e.g. generate API rst from codes),
 230 create '<your repo>/docs/pre-hook.sh' which will be executed (using 'source')
 231 once before all document build start.