Update git submodules

[opnfvdocs.git] / docs / how-to-use-docs / documentation-example.rst

diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst
index 5e2a8fb..16609e0 100644 (file)
--- 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,
 
 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
 
 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/
 
     /docs_build/
     /docs_output/

-    /releng/

 
 Index File
 ==========
 
 Index File
 ==========


@@ -62,7 +61,7 @@ Source Files
 ============
 
 Document source files have to be written in reStructuredText format (rst).
 ============
 
 Document source files have to be written in reStructuredText format (rst).

-Each file would be build as an html page and a chapter in PDF.
+Each file would be build as an html page.

 
 Here is an example source rst file :
 
 
 Here is an example source rst file :
 


@@ -82,29 +81,10 @@ Writing RST Markdown
 
 See http://sphinx-doc.org/rest.html .
 
 
 See http://sphinx-doc.org/rest.html .
 

-**Hint:**
-Table and its contents won't be adjusted, so you may need to fix your source
-text when your table is truncated in PDF version. Or, you can use 'longtable'
-option that splits your table vertically (by rows) in multiple pages.
-It is useful if you have trouble in rendering table containing many rows.
-
-.. code-block:: bash
-
-    .. table::
-        :class: longtable
-
-        +------------------------+------------+----------+----------+
-        | Header row, column 1   | Header 2   | Header 3 | Header 4 |
-        +========================+============+==========+==========+
-        | body row 1, column 1   | column 2   | column 3 | column 4 |
-        +------------------------+------------+----------+----------+
-        | body row 2             | ...        | ...      |          |
-        +------------------------+------------+----------+----------+
-

 **Hint:**
 You can add dedicated contents by using 'only' directive with build type
 **Hint:**
 You can add dedicated contents by using 'only' directive with build type

-('html' and 'pdf') for OPNFV document. But, this is not encouraged to use
-since this may make different views in HTML and PDF version.
+('html' and 'singlehtml') for OPNFV document. But, this is not encouraged to
+use since this may make different views.

 
 .. code-block:: bash
 
 
 .. code-block:: bash
 


@@ -117,37 +97,34 @@ 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
 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) :
-  [('index', '``document directory name``.tex',
-  '``document title in index.rst``', 'OPNFV', 'manual'),]
-
-See http://sphinx-doc.org/config.html to learn sphinx 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'
+* **numfig** = True
+* **master_doc** = 'index'
+* **pygments_style** = 'sphinx'
+* **html_use_index** = False
+* **html_logo** = 'opnfv-logo.png'
+* **html_sidebars** = {'**': ['globaltoc.html',
+  '``path to opnfvdocs dir``/etc/pagemenu.html',
+  'searchbox.html']}
+* **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'
+* **rst_epilog** = '    Revision:``git last commit hash``\n    Build date:``build date in year-month-date format``'

 
 **Note:**
 You can leave the file path for OPNFV logo image which will be prepared
 before each document build.
 
 
 **Note:**
 You can leave the file path for OPNFV logo image which will be prepared
 before each document build.
 

-**Hint:**
-In PDF, figures will be floated to get better view. If you want to avoid such
-automated fixes, just add this option to your conf.py after copying the default
-configuration in to the document directory.
-
-.. code-block:: bash
-
-    latex_elements = {'figure_align': 'H'}
-

 Versioning
 ==========
 
 Versioning
 ==========
 


@@ -163,9 +140,10 @@ also used in document build jobs below:
 
 .. code-block:: bash
 
 
 .. code-block:: bash
 

+    $ sudo pip install virtualenv

     $ cd /local/repo/path/to/project
     $ 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.
 
 
 Then, you can see the docs in 'docs_output' directory if build succeeded.
 


@@ -177,10 +155,11 @@ necessary packages are installed as follows:
     $ sudo pip install Sphinx==1.3.1 doc8 sphinxcontrib-httpdomain
 
 Note:
     $ 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
 
 
 Jenkins Jobs


@@ -203,8 +182,8 @@ Verify Job
 The verify job name is **opnfv-docs-verify**.
 
 When you send document changes to gerrit, jenkins will create your documents
 The verify job name is **opnfv-docs-verify**.
 
 When you send document changes to gerrit, jenkins will create your documents

-in HTML and PDF formats to verify that new document can be built successfully.
-Please check the jenkins log and artifact carefully.
+in HTML formats (normal and single-page) to verify that new document can be
+built successfully. Please check the jenkins log and artifact carefully.

 You can improve your document even though if the build job succeeded.
 
 Documents will be uploaded to
 You can improve your document even though if the build job succeeded.
 
 Documents will be uploaded to


@@ -214,11 +193,6 @@ patch set to gerrit, and deleted after the change is merged.
 Document link(s) can be found in your change page on gerrit as a review
 comment.
 
 Document link(s) can be found in your change page on gerrit as a review
 comment.
 

-Note:
-Currently, the job reports 'SUCCESS' as result of document build even if the
-PDF creation failed. This is a provisional workaround, since many projects are
-not ready for PDF creation yet.
-

 Merge Job
 ----------
 
 Merge Job
 ----------
 


@@ -233,14 +207,25 @@ latest document always.
 Sphinx Extensions
 =================
 
 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.
 
 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
 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;
+
+Hooks
+=====
+
+The document builder script supports pre-hook. If you need to execute some
+commands before starting to build process (e.g. generate API rst from codes),
+create '<your repo>/docs/pre-hook.sh' which will be executed (using 'source')
+once before all document build start.