diff options
Diffstat (limited to 'docs/how-to-use-docs')
| -rw-r--r-- | docs/how-to-use-docs/Submodules.jpg | bin | 0 -> 85389 bytes | |||
| -rw-r--r-- | docs/how-to-use-docs/addendum.rst | 80 | ||||
| -rw-r--r-- | docs/how-to-use-docs/documentation-guide.rst | 135 | ||||
| -rw-r--r-- | docs/how-to-use-docs/include-documentation.rst | 254 | ||||
| -rw-r--r-- | docs/how-to-use-docs/index.rst | 12 |
5 files changed, 481 insertions, 0 deletions
diff --git a/docs/how-to-use-docs/Submodules.jpg b/docs/how-to-use-docs/Submodules.jpg Binary files differnew file mode 100644 index 0000000..aeb7956 --- /dev/null +++ b/docs/how-to-use-docs/Submodules.jpg diff --git a/docs/how-to-use-docs/addendum.rst b/docs/how-to-use-docs/addendum.rst new file mode 100644 index 0000000..90ab1c7 --- /dev/null +++ b/docs/how-to-use-docs/addendum.rst @@ -0,0 +1,80 @@ +======== +Addendum +======== + +Index File +========== + +The index file must relatively 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 + +Source Files +============ + +Document source files have to be written in reStructuredText format (rst). +Each file would be build as an html page. + +Here is an example source rst file : + +.. code-block:: bash + + ============= + Chapter Title + ============= + + Section Title + ============= + + Subsection Title + ---------------- + + Hello! + +Writing RST Markdown +==================== + +See http://sphinx-doc.org/rest.html . + +**Hint:** +You can add dedicated contents by using 'only' directive with build type +('html' and 'singlehtml') for OPNFV document. But, this is not encouraged to +use since this may make different views. + +.. code-block:: bash + + .. only:: html + This line will be shown only in html version. + +Verify Job +---------- + +The verify job name is **docs-verify-rtd-{branch}**. + +When you send document changes to gerrit, jenkins will create your documents +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. + +Merge Job +---------- + +The merge job name is **docs-merge-rtd-{branch}**. + +Once the patch is merged, jenkins will automatically trigger building of +the new documentation. This might take about 15 minutes while readthedocs +builds the documentatation. The newly built documentation shall show up +as appropriate placed in docs.opnfv.org/{branch}/path-to-file. + diff --git a/docs/how-to-use-docs/documentation-guide.rst b/docs/how-to-use-docs/documentation-guide.rst new file mode 100644 index 0000000..fed42a4 --- /dev/null +++ b/docs/how-to-use-docs/documentation-guide.rst @@ -0,0 +1,135 @@ +=================== +Documentation Guide +=================== + +This page intends to cover the documentation handling for OPNFV. OPNFV projects are expected to create a variety of document types, +according to the nature of the project. Some of these are common to projects that develop/integrate features into the OPNFV platform, e.g. +Installation Instructions and User/Configurations Guides. Other document types may be project-specific. + +.. contents:: + :depth: 3 + :local: + +Getting Started with Documentation for Your Project +--------------------------------------------------- +OPNFV documentation is automated and integrated into our git & gerrit toolchains. + +We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact +store, our WiKi is also able to integrate these rendered documents directly allowing projects to use the revision controlled documentation +process for project information, content and deliverables. +Read :ref:`this page <include-documentation>` which elaborates on how documentation is to be included within opnfvdocs. + +Licencing your documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is contributed +in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ and the `SPDX https://spdx.org/>`_ licence. +All documentation files need to be licensed using the text below. The license may be applied in the first lines of +all contributed RST files: + +.. code-block:: bash + + .. This work is licensed under a Creative Commons Attribution 4.0 International License. + .. SPDX-License-Identifier: CC-BY-4.0 + .. (c) <optionally add copywriters name> + + These lines will not be rendered in the html and pdf files. + +How and where to store the document content files in your repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +All documentation for your project should be structured and stored in the :code:`<repo>/docs/` directory. The documentation toolchain will +look in these directories and be triggered on events in these directories when generating documents. + +Document structure and contribution +----------------------------------- +A general structure is proposed for storing and handling documents that are common across many projects but also for documents that may be +project specific. The documentation is divided into three areas Release, Development and Testing. Templates for these areas can be found +under :code:`opnfvdocs/docs/templates/`. + +Project teams are encouraged to use templates provided by the opnfvdocs project to ensure that there is consistency across the community. +Following representation shows the expected structure: + +:: + + docs/ + ├── development + │ ├── design + │ ├── overview + │ └── requirements + ├── release + │ ├── configguide + │ ├── installation + │ ├── release-notes + │ ├── scenarios + │ │ └── scenario.name + │ └── userguide + └── testing + ├── developer + └── user + + +Release documentation +^^^^^^^^^^^^^^^^^^^^^ +Release documentation is the set of documents that are published for each OPNFV release. These documents are created and developed +following the OPNFV release process and milestones and should reflect the content of the OPNFV release. +These documents have a master index.rst file in the <opnfvdocs> repository and extract content from other repositories. +To provide content into these documents place your <content>.rst files in a directory in your repository that matches the master document +and add a reference to that file in the correct place in the corresponding index.rst file in :code:`opnfvdocs/docs/release/`. + +**Platform Overview**: :code:`opnfvdocs/docs/release/overview` + +- Note this document is not a contribution driven document +- Content for this is prepared by the Marketing team together with the opnfvdocs team + +**Installation Instruction**: :code:`<repo>/docs/release/installation` + +- Folder for documents describing how to deploy each installer and scenario descriptions +- Release notes will be included here <To Confirm> +- Security related documents will be included here +- Note that this document will be compiled into 'OPNFV Installation Instruction' + +**User Guide**: :code:`<repo>/docs/release/userguide` + +- Folder for manuals to use specific features +- Folder for documents describing how to install/configure project specific components and features +- Can be the directory where API reference for project specific features are stored +- Note this document will be compiled into 'OPNFV userguide' + +**Configuration Guide**: :code:`<repo>/docs/release/configguide` + +- Brief introduction to configure OPNFV with its dependencies. + +**Release Notes**: :code:`<repo>/docs/release/release-notes` + +- Changes brought about in the release cycle. +- Include version details. + +Testing documentation +^^^^^^^^^^^^^^^^^^^^^ +Documentation created by test projects can be stored under two different sub directories /user or /developemnt. +Release notes will be stored under <repo>/docs/release/release-notes + +**User documentation**: :code:`<repo>/testing/user/` +Will collect the documentation of the test projects allowing the end user to perform testing towards a OPNFV SUT +e.g. Functest/Yardstick/Vsperf/Storperf/Bottlenecks/Qtip installation/config & user guides. + +**Development documentation**: :code:`<repo>/testing/developent/` +Will collect documentation to explain how to create your own test case and leverage existing testing frameworks e.g. developer guides. + +Development Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^ +Project specific documents such as design documentation, project overview or requirement documentation can be stored under +/docs/development. Links to generated documents will be dislayed under Development Documentaiton section on docs.opnfv.org. +You are encouraged to establish the following basic structure for your project as needed: + +**Requirement Documentation**: :code:`<repo>/docs/development/requirements/` + +- Folder for your requirement documentation +- For details on requirements projects' structures see the `Requirements Projects <https://wiki.opnfv.org/display/PROJ/Requirements+Projects>`_ page. + +**Design Documentation**: :code:`<repo>/docs/development/design` + +- Folder for your upstream design documents (blueprints, development proposals, etc..) + +**Project overview**: :code:`<repo>/docs/development/overview` + +- Folder for any project specific documentation. diff --git a/docs/how-to-use-docs/include-documentation.rst b/docs/how-to-use-docs/include-documentation.rst new file mode 100644 index 0000000..d1a5a62 --- /dev/null +++ b/docs/how-to-use-docs/include-documentation.rst @@ -0,0 +1,254 @@ +.. _include-documentation: +============================ +Including your Documentation +============================ + +.. contents:: + :depth: 3 + :local: + +In your project repository +-------------------------- + +Add your documentation to your repository in the folder structure and +according to the templates listed above. The documentation templates you +will require are available in opnfvdocs/docs/templates/ repository, you should +copy the relevant templates to your <repo>/docs/ directory in your repository. +For instance if you want to document userguide, then your steps shall be +as follows: + +.. code-block:: bash + + git clone ssh://<your_id>@gerrit.opnfv.org:29418/opnfvdocs.git + cp -p opnfvdocs/docs/userguide/* <my_repo>/docs/userguide/ + + +You should then add the relevant information to the template that will +explain the documentation. When you are done writing, you can commit +the documentation to the project repository. + +.. code-block:: bash + + git add . + git commit --signoff --all + git review + +In OPNFVDocs Composite Documentation +------------------------------------ + +In toctree ++++++++++++ + +To import project documents from project repositories, we use submodules. + Each project is stored in :code:`opnfvdocs/docs/submodule/` as follows: + +.. image:: Submodules.jpg + :scale: 50 % + +To include your project specific documentation in the composite documentation, +first identify where your project documentation should be included. +Say your project userguide should figure in the ‘OPNFV Userguide’, then: + + +.. code-block:: bash + + vim opnfvdocs/docs/release/userguide.introduction.rst + +This opens the text editor. Identify where you want to add the userguide. +If the userguide is to be added to the toctree, simply include the path to +it, example: + + +.. code-block:: bash + + .. toctree:: + :maxdepth: 1 + + submodules/functest/docs/userguide/index + submodules/bottlenecks/docs/userguide/index + submodules/yardstick/docs/userguide/index + <submodules/path-to-your-file> + +As Hyperlink +++++++++++++ + +It's pretty common to want to reference another location in the +OPNFV documentation and it's pretty easy to do with +reStructuredText. This is a quick primer, more information is in the +`Sphinx section on Cross-referencing arbitrary locations +<http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_. + +Within a single document, you can reference another section simply by:: + + This is a reference to `The title of a section`_ + +Assuming that somewhere else in the same file there a is a section +title something like:: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +It's typically better to use ``:ref:`` syntax and labels to provide +links as they work across files and are resilient to sections being +renamed. First, you need to create a label something like:: + + .. _a-label: + + The title of a section + ^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: The underscore (_) before the label is required. + +Then you can reference the section anywhere by simply doing:: + + This is a reference to :ref:`a-label` + +or:: + + This is a reference to :ref:`a section I really liked <a-label>` + +.. note:: When using ``:ref:``-style links, you don't need a trailing + underscore (_). + +Because the labels have to be unique, it usually makes sense to prefix +the labels with the project name to help share the label space, e.g., +``sfc-user-guide`` instead of just ``user-guide``. + +Once you have made these changes you need to push the patch back to +the opnfvdocs team for review and integration. + +.. code-block:: bash + + git add . + git commit --signoff --all + git review + +Be sure to add the project leader of the opnfvdocs project +as a reviewer of the change you just pushed in gerrit. + +'doc8' Validation +----------------- +It is recommended that all rst content is validated by `doc8 <https://pypi.python.org/pypi/doc8>`_ standards. +To validate your rst files using doc8, install doc8. + +.. code-block:: bash + + sudo pip install doc8 + +doc8 can now be used to check the rst files. Execute as, + +.. code-block:: bash + + doc8 --ignore D000,D001 <file> + + +Testing: Build Documentation Locally +------------------------------------ + +Composite OPNFVDOCS documentation ++++++++++++++++++++++++++++++++++ +To build whole documentation under opnfvdocs/, follow these steps: + +Install virtual environment. + +.. code-block:: bash + + sudo pip install virtualenv + cd /local/repo/path/to/project + +Download the OPNFVDOCS repository. + +.. code-block:: bash + + git clone https://gerrit.opnfv.org/gerrit/opnfvdocs + +Change directory to opnfvdocs & install requirements. + +.. code-block:: bash + + cd opnfvdocs + sudo pip install -r etc/requirements.txt + +Update submodules, build documentation using tox & then open using any browser. + +.. code-block:: bash + + cd opnfvdocs + git submodule update --init + tox -edocs + firefox docs/_build/html/index.html + +.. note:: Make sure to run `tox -edocs` and not just `tox`. + +Individual project documentation +++++++++++++++++++++++++++++++++ +To test how the documentation renders in HTML, follow these steps: + +Install virtual environment. + +.. code-block:: bash + + sudo pip install virtualenv + cd /local/repo/path/to/project + +Download the opnfvdocs repository. + +.. code-block:: bash + + git clone https://gerrit.opnfv.org/gerrit/opnfvdocs + +Change directory to opnfvdocs & install requirements. + +.. code-block:: bash + + cd opnfvdocs + sudo pip install -r etc/requirements.txt + +Move the conf.py file to your project folder where RST files have been kept: + +.. code-block:: bash + + mv opnfvdocs/docs/conf.py <path-to-your-folder>/ + +Move the static files to your project folder: + +.. code-block:: bash + + mv opnfvdocs/_static/ <path-to-your-folder>/ + +Build the documentation from within your project folder: + +.. code-block:: bash + + sphinx-build -b html <path-to-your-folder> <path-to-output-folder> + +Your documentation shall be built as HTML inside the +specified output folder directory. + +.. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content. + + +Adding your project repository as a submodule +-------------------------- + +Clone the opnfvdocs repository and your submodule to .gitmodules following the convention of the file + +.. code-block:: bash + + cd docs/submodules/ + git submodule add https://gerrit.opnfv.org/gerrit/$reponame + git submodule init $reponame/ + git submodule update $reponame/ + git add . + git commit -sv + git review + +Removing a project repository as a submodule +-------------------------- + git rm docs/submodules/$reponame + rm -rf .git/modules/$reponame + git config -f .git/config --remove-section submodule.$reponame 2> /dev/null + git add . + git commit -sv + git review + diff --git a/docs/how-to-use-docs/index.rst b/docs/how-to-use-docs/index.rst new file mode 100644 index 0000000..424f471 --- /dev/null +++ b/docs/how-to-use-docs/index.rst @@ -0,0 +1,12 @@ +.. _documentation-guide: + +=================== +Documentation Guide +=================== + +.. toctree:: + :maxdepth: 2 + + documentation-guide + include-documentation + addendum |
