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 according to the nature of the project. Some of these are common to projects that develop/integrate features into the OPNFV platform, e.g.
   7 Installation Instructions and User/Configurations Guides. Other document types may be project-specific.
   8
   9 .. contents::
  10    :depth: 3
  11    :local:
  12
  13 Getting Started with Documentation for Your Project
  14 ---------------------------------------------------
  15 OPNFV documentation is automated and integrated into our git & gerrit toolchains.
  16
  17 We use RST document templates in our repositories and automatically render to HTML and PDF versions of the documents in our artifact
  18 store, our Wiki is also able to integrate these rendered documents directly allowing projects to use the revision controlled
  19 documentation
  20 process for project information, content and deliverables.
  21 The `LFN documenatation guide <https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html>`_ explains how to enable
  22 your documenation build.
  23
  24 Licencing your documentation
  25 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  26 All contributions to the OPNFV project are done in accordance with the OPNFV licensing requirements. Documentation in OPNFV is
  27 contributed
  28 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_  and the `SPDX <https://spdx.org/>`_
  29 licence.
  30 All documentation files need to be licensed using the text below. The license may be applied in the first lines of
  31 all contributed RST files:
  32
  33 .. code-block:: bash
  34
  35  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
  36  .. SPDX-License-Identifier: CC-BY-4.0
  37  .. (c) <optionally add copywriters name>
  38
  39  These lines will not be rendered in the html and pdf files.
  40
  41 How and where to store the document content files in your repository
  42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  43 All documentation for your project should be structured and stored in the :code:`<repo>/docs/` directory. The documentation toolchain will
  44 look in these directories and be triggered on events in these directories when generating documents.
  45
  46 Document structure and contribution
  47 -----------------------------------
  48 A general structure is proposed for storing and handling documents that are common across many projects but also for documents that may be
  49 project specific. The documentation is divided into three areas Release, Development and Testing. Templates for these areas can be found
  50 under :code:`opnfvdocs/docs/templates/`.
  51
  52 Project teams are encouraged to use templates provided by the opnfvdocs project to ensure that there is consistency across the community.
  53 Following representation shows the expected structure:
  54
  55 ::
  56
  57         docs/
  58         ├── development
  59         │   ├── design
  60         │   ├── overview
  61         │   └── requirements
  62         ├── release
  63         │   ├── configguide
  64         │   ├── installation
  65         │   ├── release-notes
  66         │   ├── scenarios
  67         │   │   └── scenario.name
  68         │   └── userguide
  69         ├── testing
  70         │   ├── developer
  71         │   └── user
  72         └── infrastructure
  73             ├── hardware-infrastructure
  74             ├── software-infrastructure
  75             ├── continuous-integration
  76             └── cross-community-continuous-integration
  77
  78 Release documentation
  79 ^^^^^^^^^^^^^^^^^^^^^
  80 Release documentation is the set of documents that are published for each OPNFV release. These documents are created and developed
  81 following the OPNFV release process and milestones and should reflect the content of the OPNFV release.
  82 These documents have a master index.rst file in the <opnfvdocs> repository and extract content from other repositories.
  83 To provide content into these documents place your <content>.rst files in a directory in your repository that matches the master document
  84 and add a reference to that file in the correct place in the corresponding index.rst file in :code:`opnfvdocs/docs/release/`.
  85
  86 **Platform Overview**: :code:`opnfvdocs/docs/release/overview`
  87
  88 - Note this document is not a contribution driven document
  89 - Content for this is prepared by the Marketing team together with the opnfvdocs team
  90
  91 **Installation Instruction**: :code:`<repo>/docs/release/installation`
  92
  93 - Folder for documents describing how to deploy each installer and scenario descriptions
  94 - Release notes will be included here <To Confirm>
  95 - Security related documents will be included here
  96 - Note that this document will be compiled into 'OPNFV Installation Instruction'
  97
  98 **User Guide**: :code:`<repo>/docs/release/userguide`
  99
 100 - Folder for manuals to use specific features
 101 - Folder for documents describing how to install/configure project specific components and features
 102 - Can be the directory where API reference for project specific features are stored
 103 - Note this document will be compiled into 'OPNFV userguide'
 104
 105 **Configuration Guide**: :code:`<repo>/docs/release/configguide`
 106
 107 - Brief introduction to configure OPNFV with its dependencies.
 108
 109 **Release Notes**: :code:`<repo>/docs/release/release-notes`
 110
 111 - Changes brought about in the release cycle.
 112 - Include version details.
 113
 114 Testing documentation
 115 ^^^^^^^^^^^^^^^^^^^^^
 116 Documentation created by test projects can be stored under two different sub directories /user or /developemnt.
 117 Release notes will be stored under <repo>/docs/release/release-notes
 118
 119 **User documentation**: :code:`<repo>/testing/user/`
 120 Will collect the documentation of the test projects allowing the end user to perform testing towards a OPNFV SUT
 121 e.g. Functest/Yardstick/Vsperf/Storperf/Bottlenecks/Qtip installation/config & user guides.
 122
 123 **Development documentation**: :code:`<repo>/testing/developent/`
 124 Will collect documentation to explain how to create your own test case and leverage existing testing frameworks e.g. developer guides.
 125
 126 Development Documentation
 127 ^^^^^^^^^^^^^^^^^^^^^^^^^
 128 Project specific documents such as design documentation, project overview or requirement documentation can be stored under
 129 /docs/development. Links to generated documents will be dislayed under Development Documentaiton section on docs.opnfv.org.
 130 You are encouraged to establish the following basic structure for your project as needed:
 131
 132 **Requirement Documentation**: :code:`<repo>/docs/development/requirements/`
 133
 134 - Folder for your requirement documentation
 135 - For details on requirements projects' structures see the `Requirements Projects <https://wiki.opnfv.org/display/PROJ/Requirements+Projects>`_ page.
 136
 137 **Design Documentation**: :code:`<repo>/docs/development/design`
 138
 139 - Folder for your upstream design documents (blueprints, development proposals, etc..)
 140
 141 **Project overview**: :code:`<repo>/docs/development/overview`
 142
 143 - Folder for any project specific documentation.
 144
 145 Infrastructure Documentation
 146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 147 Infrastructure documentation can be stored under :code:`<repo>/docs/` folder of
 148 corresponding infrastructure project.