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 opnfvdocs 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.
44 This index file must refence your other rst files in that directory.
46 Here is an example index.rst :
58 documentation-example.rst
63 Document source files have to be written in reStructuredText format (rst).
64 Each file would be build as an html page.
66 Here is an example source rst file :
82 See http://sphinx-doc.org/rest.html .
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.
92 This line will be shown only in html version.
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
101 During the build process, the following default parameters are automatically
102 added if they are not set in the ``conf.py``.
105 ['sphinxcontrib.httpdomain',
106 'sphinx.ext.autodoc',
107 'sphinx.ext.viewcode',
108 'sphinx.ext.napoleon']
109 * **needs_sphinx** = '1.3'
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',
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``'
125 You can leave the file path for OPNFV logo image which will be prepared
126 before each document build.
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.
138 You can test document build in your laptop by using build script which is
139 also used in document build jobs below:
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
148 Then, you can see the docs in 'docs_output' directory if build succeeded.
150 If you have a problem of missing python package, you can make sure all
151 necessary packages are installed as follows:
155 $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
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.
168 Enabling Jenkins Jobs
169 ---------------------
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.
176 .. _jjb/opnfv/opnfv-docs.yml:
177 https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/opnfv/opnfv-docs.yml;
182 The verify job name is **opnfv-docs-verify**.
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.
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
199 The merge job name is **opnfv-docs-merge**.
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.
210 You can see available sphinx extension(s) in `opnfvdocs/etc/requirements.txt`_.
212 .. _opnfvdocs/etc/requirements.txt:
213 https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=etc/requirements.txt;
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
222 .. _opnfvdocs/scripts/docs-build.sh:
223 https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=scripts/docs-build.sh;
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.