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 releng 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     /releng/
  41
  42 Index File
  43 ==========
  44
  45 This index file must refence your other rst files in that directory.
  46
  47 Here is an example index.rst :
  48
  49 .. code-block:: bash
  50
  51     *******************
  52     Documentation Title
  53     *******************
  54
  55     .. toctree::
  56        :numbered:
  57        :maxdepth: 2
  58
  59        documentation-example.rst
  60
  61 Source Files
  62 ============
  63
  64 Document source files have to be written in reStructuredText format (rst).
  65 Each file would be build as an html page and a chapter in PDF.
  66
  67 Here is an example source rst file :
  68
  69 .. code-block:: bash
  70
  71     =============
  72     Chapter Title
  73     =============
  74
  75     Section Title
  76     =============
  77
  78     Hello!
  79
  80 Writing RST Markdown
  81 ====================
  82
  83 See http://sphinx-doc.org/rest.html .
  84
  85 You can add dedicated contents by using 'only' directive with build type
  86 ('html' and 'pdf') for OPNFV document
  87
  88 Example :
  89
  90 .. code-block:: bash
  91
  92     .. only:: html
  93         This line will be shown only in html version.
  94
  95 Configuration
  96 =============
  97
  98 If you need to change the default configuration for document build, create
  99 new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
 100 that will be used in build process instead of default for OPNFV document
 101 build. The OPNFV default configuration can be found in releng repo
 102 (see `docs/etc/conf.py`_).
 103
 104 .. _docs/etc/conf.py:
 105     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py;
 106
 107 In the build process, the following parameters are automatically added if they
 108 are not set in the conf.py .
 109
 110 * **release**, **version** : ``git last tag name`` (``git last commit hash``)
 111 * **project** : ``git repo name``
 112 * **copyright** : ``year``, OPNFV
 113 * **latex_documents** (set of pdf configuration) :
 114   [('index', '``document directory name``.tex',
 115   '``document title in index.rst``', 'OPNFV', 'manual'),]
 116
 117 See http://sphinx-doc.org/config.html to learn sphinx configuration.
 118
 119 Note: you can leave the file path for OPNFV logo image which will be prepared
 120 before each document build.
 121
 122 Versioning
 123 ==========
 124
 125 The relevant release and version information will be added to your documents
 126 by using tags from your project's git repository.
 127 The tags will be applied by Releng Project.
 128
 129 Testing
 130 =======
 131
 132 You can test document build in your laptop by using build script which is
 133 also used in document build jobs below:
 134
 135 .. code-block:: bash
 136
 137     $ cd /local/repo/path/to/project
 138     $ git clone https://git.opnfv.org/releng
 139     $ ./releng/utils/docs-build.sh
 140
 141 Then, you can see the docs in 'docs_output' directory if build succeeded.
 142
 143 If you have a problem of missing python package, you can make sure all
 144 necessary packages are installed as follows:
 145
 146 .. code-block:: bash
 147
 148     $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
 149
 150 Note:
 151 Developers are encouraged to use "ssh://<username>@gerrit.opnfv.org:29418/releng"
 152 instead of "https://git.opnfv.org/releng", so that you can quickly start
 153 development in releng.
 154 See https://wiki.opnfv.org/developer/getting_started for more detail.
 155
 156
 157 Jenkins Jobs
 158 ============
 159
 160 Enabling Jenkins Jobs
 161 ---------------------
 162
 163 Jenkins in OPNFV infra performs the jobs to verify and update your documents.
 164 To make your project repository watched by Jenkins to execute those jobs, you
 165 have to add your project name in 'project-pattern' of the following jobs by
 166 sending patch to update `jjb/opnfv/opnfv-docs.yml`_ on gerrit.
 167
 168 .. _jjb/opnfv/opnfv-docs.yml:
 169     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/opnfv/opnfv-docs.yml;
 170
 171 Verify Job
 172 ----------
 173
 174 The verify job name is **opnfv-docs-verify**.
 175
 176 When you send document changes to gerrit, jenkins will create your documents
 177 in HTML and PDF formats to verify that new document can be built successfully.
 178 Please check the jenkins log and artifact carefully.
 179 You can improve your document even though if the build job succeeded.
 180
 181 Documents will be uploaded to
 182 ``http://artifacts.opnfv.org/review/<Change Number>/`` for review.
 183 Those documents will be replaced if you update the change by sending new
 184 patch set to gerrit, and deleted after the change is merged.
 185 Document link(s) can be found in your change page on gerrit as a review
 186 comment.
 187
 188 Note:
 189 Currently, the job reports 'SUCCESS' as result of document build even if the
 190 PDF creation failed. This is a provisional workaround, since many projects are
 191 not ready for PDF creation yet.
 192
 193 Merge Job
 194 ----------
 195
 196 The merge job name is **opnfv-docs-merge**.
 197
 198 Once you are happy with the look of your documentation, you can submit the
 199 change. Then, the merge job will upload latest build documents to
 200 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
 201 You can put links in your project wiki page, so that everyone can see the
 202 latest document always.
 203
 204 Sphinx Extensions
 205 =================
 206
 207 You can see available sphinx extension(s) in `docs/etc/requirements.txt`_.
 208
 209 .. _docs/etc/requirements.txt:
 210     https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/requirements.txt;
 211
 212 You can use other sphinx extensions to improve your documents.
 213 To share such tips, we encourage you to enable the extension in OPNFV infra
 214 by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
 215 (proposing change in `docs/etc/conf.py`_ and `docs/etc/requirements.txt`_).
 216 After quick sanity checks, we'll install python package (if needed) and make
 217 it available in OPNFV document build.