diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/etc/conf.py | 20 | ||||
| -rw-r--r-- | docs/how-to-use-docs/documentation-example.rst | 172 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 15 | ||||
| -rw-r--r-- | docs/jenkins-job-builder/index.rst | 10 | ||||
| -rw-r--r-- | docs/jenkins-job-builder/opnfv-jjb-usage.rst | 3 |
5 files changed, 153 insertions, 67 deletions
diff --git a/docs/etc/conf.py b/docs/etc/conf.py index f42b11055..147c50b7d 100644 --- a/docs/etc/conf.py +++ b/docs/etc/conf.py @@ -1,15 +1,13 @@ ''' -Base configuration file for sphinx-build. +Base configuration file for building OPNFV docs You can override this configuration by putting 'conf.py' in the document -directory (e.g. how-to-use-docs/conf.py). If there is no 'conf.py' in the -document directory, this file will be copied to that directory before the -document builder jobs in 'opnfv-docs-verify' and 'opnfv-docs-merge'. -The logo image (opnfv-logo.png) will be also copied from -docs/etc/opnfv-logo.png during the build jobs. -''' +directory (e.g. docs/how-to-use-docs/conf.py). If there is no 'conf.py' +in the document directory, this file will be copied to that directory +before the document builder jobs ('opnfv-docs-verify' and 'opnfv-docs-merge'). -import datetime +See https://wiki.opnfv.org/documentation/tools . +''' needs_sphinx = '1.3' master_doc = 'index' @@ -19,9 +17,5 @@ html_use_index = False numfig = True html_logo = 'opnfv-logo.png' -latex_elements = {'printindex': ''} +latex_domain_indices = False latex_logo = 'opnfv-logo.png' - -copyright = u'%s, OPNFV' % datetime.date.today().year -version = u'1.0.0' -release = u'1.0.0' diff --git a/docs/how-to-use-docs/documentation-example.rst b/docs/how-to-use-docs/documentation-example.rst index e18ce598b..5fc2b1420 100644 --- a/docs/how-to-use-docs/documentation-example.rst +++ b/docs/how-to-use-docs/documentation-example.rst @@ -1,70 +1,172 @@ +================================================== How to create documentation for your OPNFV project ================================================== -this is the directory structure of the docs/ directory that can be found in the root of your project directory +Directory Structure +=================== + +This is the directory structure of the docs/ directory which have to be placed +in the root of your project directory. .. code-block:: bash - ./etc - ./etc/opnfv-logo.png - ./etc/conf.py - ./how-to-use-docs ./how-to-use-docs/documentation-example.rst ./how-to-use-docs/index.rst -To create your own documentation, Create any number of directories (depending on your need) and place in each of them an index.rst. -This index file must refence your other rst files. +To create your own document, create any number of directories (depending +on your need, e.g. manual) under the docs/ and place an index.rst in each +directories. +The depth of all directory should be one, so that you can make sure that +all directory names are unique. If you want to have set of all documents in +your repo, create new ``docs/all/index.rst`` and list document links in OPNFV +artifact server (artifact.opnfv.org) instead of including all other rst files +or having ``docs/index.rst``, in order to avoid having duplicated contents in +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. + +Index File +========== + +This index file must refence your other rst files in that directory. + +Here is an example index.rst : + +.. code-block:: bash + + ******************* + Documentation Title + ******************* + + .. toctree:: + :numbered: + :maxdepth: 2 + + documentation-example.rst -* Here is an example index.rst +Source Files +============ + +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. + +Here is an example source rst file : .. code-block:: bash - ===================== - Example Documentation - ===================== + ============= + Chapter Title + ============= - Contents: + Section Title + ============= - .. toctree:: - :numbered: - :maxdepth: 4 + Hello! - documentation-example.rst +Writing RST Markdown +==================== - .. - Leave these at the bottom of 'index.rst' file +See http://sphinx-doc.org/rest.html . - Revision: _sha1_ +You can add dedicated contents by using 'only' directive with build type +('html' and 'pdf') for OPNFV document - Build date: |today| +Example : +.. code-block:: bash -The Sphinx Build -================ + .. only:: html + This line will be shown only in html version. -When you push documentation changes to gerrit a jenkins job will create html documentation. +Configuration +============= -* Verify Jobs +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 `conf.py`_). -For verify jobs a link to the documentation will show up as a comment in gerrit for you to see the result. +.. _conf.py: + https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=docs/etc/conf.py; -* Merge jobs +In the build process, the following parameters are automatically added if they +are not set in the conf.py . -Once you are happy with the look of your documentation you can submit the patchset the merge job will -copy the output of each documentation directory to http://artifacts.opnfv.org/$project/docs/$name_of_your_folder/index.html +* **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'),] -Here are some quick examples of how to use rst markup +See http://sphinx-doc.org/config.html to learn sphinx configuration. -This is a headline:: +Note: you can leave the file path for OPNFV logo image which will be prepared +before each document build. - here is some code, note that it is indented +Versioning +========== -links are easy to add: Here is a link to sphinx, the tool that we are using to generate documetation http://sphinx-doc.org/ +The relevant release and version information will be added to your documents +by using tags from your project's git repository. +The tags will be applied by Releng Project. -* Bulleted Items +Testing +======= - **this will be bold** +You can test document build in your laptop by using build script which is +used in document build jobs: .. code-block:: bash - echo "Heres is a code block with bash syntax highlighting" + $ cd /loacal/repo/path/to/project + $ git clone ssh://gerrit.opnfv.org:29418/releng + $ ./releng/utils/docs-build.sh + +Then, you can see docs in 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. + +.. code-block:: bash + + /build/ + /output/ + /releng/ + +Verify Jobs +=========== + +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. +You can improve your document even though if the build job succeeded. + +Documents will be uploaded to +``http://artifacts.opnfv.org/review/<Change Number>/`` for review. +Those documents will be replaced if you update the change by sending new +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. + +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 Jobs +========== + +The merge job name is **opnfv-docs-merge**. + +Once you are happy with the look of your documentation, you can submit the +change. Then, the merge job will upload latest build documents to +``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. diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst index 0965eb3cd..8e4dbd266 100644 --- a/docs/how-to-use-docs/index.rst +++ b/docs/how-to-use-docs/index.rst @@ -1,19 +1,12 @@ .. - This is new template created on Thu Nov 26 16:18:09 JST 2015 + This is new template created on Nov 27, 2015. -===================== +********************* Example Documentation -===================== +********************* .. toctree:: :numbered: - :maxdepth: 4 + :maxdepth: 2 documentation-example.rst - -.. - Leave these at the bottom of 'index.rst' file - -Revision: _sha1_ - -Build date: |today| diff --git a/docs/jenkins-job-builder/index.rst b/docs/jenkins-job-builder/index.rst index f8f568339..b85b1320f 100644 --- a/docs/jenkins-job-builder/index.rst +++ b/docs/jenkins-job-builder/index.rst @@ -1,13 +1,9 @@ -=========================== +*************************** Release Engineering Project -=========================== +*************************** .. toctree:: :numbered: - :maxdepth: 8 + :maxdepth: 2 opnfv-jjb-usage.rst - -Revision: _sha1_ - -Build date: |today| diff --git a/docs/jenkins-job-builder/opnfv-jjb-usage.rst b/docs/jenkins-job-builder/opnfv-jjb-usage.rst index 4aecc6de6..7daacaffb 100644 --- a/docs/jenkins-job-builder/opnfv-jjb-usage.rst +++ b/docs/jenkins-job-builder/opnfv-jjb-usage.rst @@ -1,5 +1,6 @@ +=========================================== Creating/Configuring/Verifying Jenkins Jobs -============================================ +=========================================== Clone the repo:: |