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.
33 This index file must refence your other rst files in that directory.
35 Here is an example index.rst :
47 documentation-example.rst
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.
55 Here is an example source rst file :
71 See http://sphinx-doc.org/rest.html .
73 You can add dedicated contents by using 'only' directive with build type
74 ('html' and 'pdf') for OPNFV document
81 This line will be shown only in html version.
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`_).
93 https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py;
95 In the build process, the following parameters are automatically added if they
96 are not set in the conf.py .
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'),]
105 See http://sphinx-doc.org/config.html to learn sphinx configuration.
107 Note: you can leave the file path for OPNFV logo image which will be prepared
108 before each document build.
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.
120 You can test document build in your laptop by using build script which is
121 used in document build jobs:
125 $ cd /loacal/repo/path/to/project
126 $ git clone ssh://gerrit.opnfv.org:29418/releng
127 $ ./releng/utils/docs-build.sh
129 Then, you can see docs in output directory if build succeeded.
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
144 The verify job name is **opnfv-docs-verify**.
146 When you send document changes to gerrit, jenkins will create your documents
147 in HTML and PDF formats to verify that new document can be built successfully.
148 Please check the jenkins log and artifact carefully.
149 You can improve your document even though if the build job succeeded.
151 Documents will be uploaded to
152 ``http://artifacts.opnfv.org/review/<Change Number>/`` for review.
153 Those documents will be replaced if you update the change by sending new
154 patch set to gerrit, and deleted after the change is merged.
155 Document link(s) can be found in your change page on gerrit as a review
159 Currently, the job reports 'SUCCESS' as result of document build even if the
160 PDF creation failed. This is a provisional workaround, since many projects are
161 not ready for PDF creation yet.
166 The merge job name is **opnfv-docs-merge**.
168 Once you are happy with the look of your documentation, you can submit the
169 change. Then, the merge job will upload latest build documents to
170 ``http://artifacts.opnfv.org/<Project Name>/docs/`` .
171 You can put links in your project wiki page, so that everyone can see the
172 latest document always.
177 You can see available sphinx extension(s) in `docs/etc/requirements.txt`_.
179 .. _docs/etc/requirements.txt:
180 https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/requirements.txt;
182 You can use other sphinx extensions to improve your documents.
183 To share such tips, we encourage you to enable the extension in OPNFV infra
184 by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
185 (proposing change in `docs/etc/conf.py`_ and `docs/etc/requirements.txt`_).
186 After quick sanity checks, we'll install python package (if needed) and make
187 it available in OPNFV document build.