docs/how-to-use-docs/documentation-guide.rst

   1 ===================
   2 Documentation Guide
   3 ===================
   4
   5 This page intends to cover the documentation handling for OPNFV. OPNFV projects are expected to create a variety of document types.
   6
   7 .. contents::
   8    :depth: 3
   9    :local:
  10
  11 Getting Started with Documentation for Your Project
  12 ---------------------------------------------------
  13 OPNFV documentation is automated and integrated into our git & gerrit toolchains.
  14
  15 We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact
  16 store.
  17
  18 The `LFN documenatation guide <https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html>`_ explains how to enable
  19 your documenation build.
  20
  21 Licencing your documentation
  22 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  23 All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is
  24 contributed
  25 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_  and the `SPDX <https://spdx.org/>`_
  26 licence.
  27 All documentation files need to be licensed using the text below. The license may be applied in the first lines of
  28 all contributed RST files:
  29
  30 .. code-block:: bash
  31
  32  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
  33  .. SPDX-License-Identifier: CC-BY-4.0
  34  .. (c) <optionally add copywriters name>
  35
  36  These lines will not be rendered in the html and pdf files.
  37
  38 How and where to store the document content files in your repository
  39 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  40 All documentation for your project should be structured and stored in the :code:`<repo>/docs/` directory. The documentation toolchain will
  41 look in these directories and be triggered on events in these directories when generating documents.
  42
  43 Document structure and contribution
  44 -----------------------------------
  45 A general structure is proposed for storing and handling documents that are common across many projects but also for documents that may be
  46 project specific. The documentation is divided into three areas Release, Testing and Infrastructure. Templates for these areas can be found
  47 under :code:`opnfvdocs/docs/templates/`.
  48
  49 Project teams are encouraged to use templates provided by the opnfvdocs project to ensure that there is consistency across the community.
  50 Following representation shows the expected structure:
  51
  52 ::
  53
  54         docs/
  55         ├── release
  56         │   ├── installation
  57         │   ├── user and configuration guide
  58         │   └── release notes
  59         ├── testing
  60         │   ├── user guide
  61         │   ├── developer guide
  62         ├── infrastructure
  63         │   ├── infrastructure overview
  64         │   ├── continuous integration (CI)
  65         │   ├── cross community continuous integration (XCI)
  66
  67
  68 Release documentation
  69 ^^^^^^^^^^^^^^^^^^^^^
  70 Release documentation is the set of documents that are published for each OPNFV release. These documents are created and developed
  71 following the OPNFV release process and milestones and should reflect the content of the OPNFV release.
  72
  73 **Installation Instruction**: :code:`<repo>/docs/release/installation`
  74
  75 - This document is shall describe how to get started and install OPNFV'
  76
  77 **User Guide**: :code:`<repo>/docs/release/userguide`
  78
  79 - This document shall describe the usage of a OPNFV component'
  80
  81 **Configuration Guide**: :code:`<repo>/docs/release/configguide`
  82
  83 - Brief introduction to configure a OPNFV component'
  84
  85 **Release Notes**: :code:`<repo>/docs/release/release-notes`
  86
  87 - Applicable for all projects participating in a release'
  88
  89 Testing documentation
  90 ^^^^^^^^^^^^^^^^^^^^^
  91 Documentation created by test projects can be stored under two different sub directories /user or /developemnt.
  92 Release notes will be stored under <repo>/docs/release/release-notes
  93
  94 **User documentation**: :code:`<repo>/testing/user/`
  95 Will collect the documentation of the test projects allowing the end user to perform testing towards a OPNFV SUT
  96 e.g. Functest/Yardstick/Vsperf/Storperf/Bottlenecks/Qtip installation/config & user guides.
  97
  98 **Development documentation**: :code:`<repo>/testing/developent/`
  99 Will collect documentation to explain how to create your own test case and leverage existing testing frameworks e.g. developer guides.
 100
 101 Infrastructure Documentation
 102 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 103 Infrastructure documentation can be stored under :code:`<repo>/docs/` folder of
 104 corresponding infrastructure project.