1 ==================================================
2 How to create documentation for your OPNFV project
3 ==================================================
8 This is the directory structure of the docs/ directory which have to be placed
9 in the root of your project directory.
13 ./how-to-use-docs/documentation-example.rst
14 ./how-to-use-docs/index.rst
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
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
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.
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.
45 This index file must refence your other rst files in that directory.
47 Here is an example index.rst :
59 documentation-example.rst
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.
67 Here is an example source rst file :
83 See http://sphinx-doc.org/rest.html .
86 Table and its contents won't be adjusted, so you may need to fix your source
87 text when your table is truncated in PDF version. Or, you can use 'longtable'
88 option that splits your table vertically (by rows) in multiple pages.
89 It is useful if you have trouble in rendering table containing many rows.
96 +------------------------+------------+----------+----------+
97 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
98 +========================+============+==========+==========+
99 | body row 1, column 1 | column 2 | column 3 | column 4 |
100 +------------------------+------------+----------+----------+
101 | body row 2 | ... | ... | |
102 +------------------------+------------+----------+----------+
105 You can add dedicated contents by using 'only' directive with build type
106 ('html' and 'pdf') for OPNFV document. But, this is not encouraged to use
107 since this may make different views in HTML and PDF version.
112 This line will be shown only in html version.
117 If you need to change the default configuration for document build, create
118 new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
119 that will be used in build process instead of default for OPNFV document
120 build. The OPNFV default configuration can be found in releng repo
121 (see `docs/etc/conf.py`_).
123 .. _docs/etc/conf.py:
124 https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py;
126 In the build process, the following parameters are automatically added if they
127 are not set in the conf.py .
129 * **release**, **version** : ``git last tag name`` (``git last commit hash``)
130 * **project** : ``git repo name``
131 * **copyright** : ``year``, OPNFV
132 * **latex_documents** (set of pdf configuration) :
133 [('index', '``document directory name``.tex',
134 '``document title in index.rst``', 'OPNFV', 'manual'),]
136 See http://sphinx-doc.org/config.html to learn sphinx configuration.
139 You can leave the file path for OPNFV logo image which will be prepared
140 before each document build.
143 In PDF, figures will be floated to get better view. If you want to avoid such
144 automated fixes, just add this option to your conf.py after copying the default
145 configuration in to the document directory.
149 latex_elements = {'figure_align': 'H'}
154 The relevant release and version information will be added to your documents
155 by using tags from your project's git repository.
156 The tags will be applied by Releng Project.
161 You can test document build in your laptop by using build script which is
162 also used in document build jobs below:
166 $ cd /local/repo/path/to/project
167 $ git clone https://git.opnfv.org/releng
168 $ ./releng/utils/docs-build.sh
170 Then, you can see the docs in 'docs_output' directory if build succeeded.
172 If you have a problem of missing python package, you can make sure all
173 necessary packages are installed as follows:
177 $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
180 Developers are encouraged to use "ssh://<username>@gerrit.opnfv.org:29418/releng"
181 instead of "https://git.opnfv.org/releng", so that you can quickly start
182 development in releng.
183 See https://wiki.opnfv.org/developer/getting_started for more detail.
189 Enabling Jenkins Jobs
190 ---------------------
192 Jenkins in OPNFV infra performs the jobs to verify and update your documents.
193 To make your project repository watched by Jenkins to execute those jobs, you
194 have to add your project name in 'project-pattern' of the following jobs by
195 sending patch to update `jjb/opnfv/opnfv-docs.yml`_ on gerrit.
197 .. _jjb/opnfv/opnfv-docs.yml:
198 https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/opnfv/opnfv-docs.yml;
203 The verify job name is **opnfv-docs-verify**.
205 When you send document changes to gerrit, jenkins will create your documents
206 in HTML and PDF formats to verify that new document can be built successfully.
207 Please check the jenkins log and artifact carefully.
208 You can improve your document even though if the build job succeeded.
210 Documents will be uploaded to
211 ``http://artifacts.opnfv.org/review/<Change Number>/`` for review.
212 Those documents will be replaced if you update the change by sending new
213 patch set to gerrit, and deleted after the change is merged.
214 Document link(s) can be found in your change page on gerrit as a review
218 Currently, the job reports 'SUCCESS' as result of document build even if the
219 PDF creation failed. This is a provisional workaround, since many projects are
220 not ready for PDF creation yet.
225 The merge job name is **opnfv-docs-merge**.
227 Once you are happy with the look of your documentation, you can submit the
228 change. Then, the merge job will upload latest build documents to
229 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
230 You can put links in your project wiki page, so that everyone can see the
231 latest document always.
236 You can see available sphinx extension(s) in `docs/etc/requirements.txt`_.
238 .. _docs/etc/requirements.txt:
239 https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/requirements.txt;
241 You can use other sphinx extensions to improve your documents.
242 To share such tips, we encourage you to enable the extension in OPNFV infra
243 by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
244 (proposing change in `docs/etc/conf.py`_ and `docs/etc/requirements.txt`_).
245 After quick sanity checks, we'll install python package (if needed) and make
246 it available in OPNFV document build.