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