You may have "docs/how-to-use-docs/" in you project repo. You can delete it,
since it is sample and master version is stored in releng repo.
+Note:
+During the document build process, 'docs_build' and 'docs_output' will be
+created in the project root directory. To avoid conflict, you should not
+use those names and should add the following entries in '.gitignore' file
+so that git can ignore built files.
+
+.. code-block:: bash
+
+ /docs_build/
+ /docs_output/
+ /releng/
+
Index File
==========
new conf.py in the document directory (e.g. 'docs/how-to-use-docs/conf.py')
that will be used in build process instead of default for OPNFV document
build. The OPNFV default configuration can be found in releng repo
-(see `conf.py`_).
+(see `docs/etc/conf.py`_).
-.. _conf.py:
+.. _docs/etc/conf.py:
https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py;
In the build process, the following parameters are automatically added if they
=======
You can test document build in your laptop by using build script which is
-used in document build jobs:
+also used in document build jobs below:
.. code-block:: bash
- $ cd /loacal/repo/path/to/project
- $ git clone ssh://gerrit.opnfv.org:29418/releng
+ $ cd /local/repo/path/to/project
+ $ git clone https://git.opnfv.org/releng
$ ./releng/utils/docs-build.sh
-Then, you can see docs in output directory if build succeeded.
+Then, you can see the docs in 'docs_output' directory if build succeeded.
-This script will generate files in 'build' and 'output'. You should consider
-to add the following entries in '.gitignore' file, so that git can ignore
-built files.
+If you have a problem of missing python package, you can make sure all
+necessary packages are installed as follows:
.. code-block:: bash
- /build/
- /output/
- /releng/
+ $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
+
+Note:
+Developers are encouraged to use "ssh://<username>@gerrit.opnfv.org:29418/releng"
+instead of "https://git.opnfv.org/releng", so that you can quickly start
+development in releng.
+See https://wiki.opnfv.org/developer/getting_started for more detail.
+
-Verify Jobs
-===========
+Jenkins Jobs
+============
+
+Enabling Jenkins Jobs
+---------------------
+
+Jenkins in OPNFV infra performs the jobs to verify and update your documents.
+To make your project repository watched by Jenkins to execute those jobs, you
+have to add your project name in 'project-pattern' of the following jobs by
+sending patch to update `jjb/opnfv/opnfv-docs.yml`_ on gerrit.
+
+.. _jjb/opnfv/opnfv-docs.yml:
+ https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/opnfv/opnfv-docs.yml;
+
+Verify Job
+----------
The verify job name is **opnfv-docs-verify**.
PDF creation failed. This is a provisional workaround, since many projects are
not ready for PDF creation yet.
-Merge Jobs
-==========
+Merge Job
+----------
The merge job name is **opnfv-docs-merge**.
``http://artifacts.opnfv.org/<Project Name>/docs/`` .
You can put links in your project wiki page, so that everyone can see the
latest document always.
+
+Sphinx Extensions
+=================
+
+You can see available sphinx extension(s) in `docs/etc/requirements.txt`_.
+
+.. _docs/etc/requirements.txt:
+ https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/requirements.txt;
+
+You can use other sphinx extensions to improve your documents.
+To share such tips, we encourage you to enable the extension in OPNFV infra
+by asking releng and opnfvdocs teams to add new sphinx extension via gerrit
+(proposing change in `docs/etc/conf.py`_ and `docs/etc/requirements.txt`_).
+After quick sanity checks, we'll install python package (if needed) and make
+it available in OPNFV document build.
Code Review / releng.git / blobdiff