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

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3
   4 Documentation Guide
   5 ===================
   6
   7 This page describes how documentation is created for the Open Network Automation Platform (ONAP).
   8 ONAP projects create a variety of document types depending on the nature of the project.
   9 Some projects will create detailed technical descriptions such as configuration parameters or how to
  10 use or extend the functionality of platform component.
  11 These descriptions may be together as a reference for that project and/or
  12 be used in documents tailored to a specific user audience and task they are performing.
  13
  14 Acknowledgement
  15 ---------------
  16
  17 Much of the content in this document is derived from similar documentation processes used in other Linux Foundation Projects
  18 including OPNFV and Open Daylight.
  19
  20 .. contents::
  21    :depth: 3
  22    :local:
  23
  24 Getting Started
  25 ---------------
  26 ONAP documentation is stored in git repositories, changes are managed with gerrit reviews, and published documents
  27 automatically generated when there is a change in any source used to build the documentation.
  28
  29 Authors create source for documents in reStructured Text (RST) that is automatically rendered to HTML and PDF
  30 and published on Readthedocs.io.
  31 The developer Wiki can reference these rendered documents directly allowing projects to
  32 easily maintain current release documentation.
  33 Read :ref:`this page <include-documentation>` which describes how documentation is created from
  34 ONAP Documentation project (doc) documentation source and other ONAP projects providing source material.
  35
  36 Licencing Your Documentation
  37 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  38 All contributions to the ONAP project are done in accordance with the ONAP licensing requirements.
  39 Documentation in ONAP is contributed
  40 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
  41 All documentation files need to be licensed using the text below. The license may be applied in the first lines of
  42 all contributed RST files:
  43
  44 .. code-block:: bash
  45
  46  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
  47  .. (c) <optionally add copywriters name>
  48
  49  These lines will not be rendered in the html and pdf files.
  50
  51 Storing Content Files in Your Repository
  52 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  53 All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory.
  54 The documentation tool chain will look in these directories when triggered by verify and merge events.
  55
  56 .. index:: master, document
  57
  58 Document Structure and Contribution
  59 -----------------------------------
  60 A top level master_document structure is proposed for organizing all documents
  61 in the four areas as shown below with additional detail under each area.
  62 This structure may change as we gain experience with the first release of ONAP.
  63
  64
  65 ::
  66
  67         docs/
  68         ├── release
  69         │   ├── overview
  70         │   ├── architecture
  71         │   ├── use-cases
  72         │   ├── tutorials
  73         │   └── release-notes
  74         ├── onap-developer
  75         │   ├── design
  76         │   ├── develop
  77         │   ├── document
  78         │   └── test
  79         ├── adminstrator
  80         │   ├── configure
  81         │   ├── deploy
  82         │   └── operate
  83         ├── service-designer
  84         │   ├── deploy
  85         │   ├── design
  86         │   └── portal
  87         └── vnf-provider
  88             ├── guidelines
  89             └── sdk
  90
  91 Templates
  92 ^^^^^^^^^
  93 Where multiple sections with similar content are expected, templates can be created and stored
  94 under `doc/docs/templates/` and used a starting point for similar content.
  95 For example the high level architecture and interface information for an ONAP component.
  96 A template is a directory name in `doc/docs/templates` , the directory contains at least an
  97 index.rst file with a starting point for creating content, and as needed
  98 references to other sources in the template directory.  Current templates are shown below.
  99
 100 .. toctree::
 101    :maxdepth: 1
 102
 103    ../../../templates/index
 104
 105 Project teams are encouraged to reuse and propose new templates for reuse.
 106
 107 Release Documentation
 108 ^^^^^^^^^^^^^^^^^^^^^
 109 Release documentation is the set of documents that are published for each ONAP release.
 110 The documents have a master index.rst file in the <doc> repository and reference content as needed
 111 from other project repository.
 112 To provide content for these other projects place <content>.rst files in a directory
 113 in your repository that
 114 matches the master document and add a reference to that file in the correct place in the
 115 corresponding master index.rst.
 116