diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 68 |
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; |