diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 73 |
1 files changed, 59 insertions, 14 deletions
diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst index bab2ee157..5e2a8fb00 100644 --- a/docs/how-to-use-docs/documentation-example.rst +++ b/docs/how-to-use-docs/documentation-example.rst @@ -27,6 +27,18 @@ 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. +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 ========== @@ -70,10 +82,29 @@ Writing RST Markdown See http://sphinx-doc.org/rest.html . -You can add dedicated contents by using 'only' directive with build type -('html' and 'pdf') for OPNFV document +**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 -Example : + +------------------------+------------+----------+----------+ + | 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 +('html' and 'pdf') for OPNFV document. But, this is not encouraged to use +since this may make different views in HTML and PDF version. .. code-block:: bash @@ -104,9 +135,19 @@ are not set in the conf.py . See http://sphinx-doc.org/config.html to learn sphinx configuration. -Note: you can leave the file path for OPNFV logo image which will be prepared +**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 ========== @@ -118,25 +159,29 @@ Testing ======= 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 - /docs_build/ - /docs_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. + Jenkins Jobs ============ |