summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/how-to-use-docs/documentation-example.rst68
1 files changed, 40 insertions, 28 deletions
diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst
index 5e2a8fb00..33261eff4 100644
--- a/docs/how-to-use-docs/documentation-example.rst
+++ b/docs/how-to-use-docs/documentation-example.rst
@@ -25,7 +25,7 @@ your documents.
Note:
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.
+since it is sample and master version is stored in opnfvdocs repo.
Note:
During the document build process, 'docs_build' and 'docs_output' will be
@@ -37,7 +37,6 @@ so that git can ignore built files.
/docs_build/
/docs_output/
- /releng/
Index File
==========
@@ -117,21 +116,30 @@ Configuration
If you need to change the default configuration for document build, create
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 `docs/etc/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
-are not set in the conf.py .
-
-* **release**, **version** : ``git last tag name`` (``git last commit hash``)
-* **project** : ``git repo name``
-* **copyright** : ``year``, OPNFV
-* **latex_documents** (set of pdf configuration) :
+build.
+During the build process, the following default parameters are automatically
+added if they are not set in the ``conf.py``.
+
+* **extensions** =
+ ['sphinxcontrib.httpdomain',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.viewcode',
+ 'sphinx.ext.napoleon']
+* **needs_sphinx** = '1.3'
+* **master_doc** = 'index'
+* **pygments_style** = 'sphinx'
+* **html_use_index** = False
+* **numfig** = True
+* **html_logo** = 'opnfv-logo.png'
+* **latex_domain_indices** = False
+* **latex_logo** = 'opnfv-logo.png'
+* **latex_documents** =
[('index', '``document directory name``.tex',
'``document title in index.rst``', 'OPNFV', 'manual'),]
+* **release** = '``git last tag name`` (``git last commit hash``)'
+* **version** = '``git last tag name`` (``git last commit hash``)'
+* **project** = '``git repo name``'
+* **copyright** = '``year``, OPNFV'
See http://sphinx-doc.org/config.html to learn sphinx configuration.
@@ -164,8 +172,8 @@ also used in document build jobs below:
.. code-block:: bash
$ cd /local/repo/path/to/project
- $ git clone https://git.opnfv.org/releng
- $ ./releng/utils/docs-build.sh
+ $ git clone https://git.opnfv.org/opnfvdocs docs_build/_opnfvdocs
+ $ ./docs_build/_opnfvdocs/scripts/docs-build.sh
Then, you can see the docs in 'docs_output' directory if build succeeded.
@@ -177,10 +185,11 @@ necessary packages are installed as follows:
$ 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.
+Developers are encouraged to use
+"ssh://<username>@gerrit.opnfv.org:29418/opnfvdocs"
+instead of "https://git.opnfv.org/opnfvdocs", so that you can quickly start
+development in opnfvdocs.
+See https://wiki.opnfv.org/display/DEV/Developer+Getting+Started for more detail.
Jenkins Jobs
@@ -233,14 +242,17 @@ latest document always.
Sphinx Extensions
=================
-You can see available sphinx extension(s) in `docs/etc/requirements.txt`_.
+You can see available sphinx extension(s) in `opnfvdocs/etc/requirements.txt`_.
-.. _docs/etc/requirements.txt:
- https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/requirements.txt;
+.. _opnfvdocs/etc/requirements.txt:
+ https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=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
+To share such improvements, 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.
+(proposing change in `opnfvdocs/scripts/docs-build.sh`_ and `opnfvdocs/etc/requirements.txt`_).
+After quick sanity checks, we'll merge the patch to make it available in OPNFV
+document build.
+
+.. _opnfvdocs/scripts/docs-build.sh:
+ https://gerrit.opnfv.org/gerrit/gitweb?p=opnfvdocs.git;a=blob;f=scripts/docs-build.sh;