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 that may be used as a standalone reference for that project and/or
  11 be used in larger end to end documents tailored to a specific user audience and task they are performing.
  12
  13 Acknowledgement
  14 ---------------
  15
  16 Much of the content in this document is derived from similar documentation processes used in other Linux Foundation Projects
  17 including OPNFV and Open Daylight.
  18
  19 .. contents::
  20    :depth: 3
  21    :local:
  22
  23 Getting Started
  24 ---------------
  25 ONAP documentation is stored in git repositories, changes are managed with gerrit reviews, and published documents
  26 automatically generated when there is a change in any source used to build the documentation.
  27
  28 Authors create source for documents in reStructured Text (RST) that is automatically rendered to HTML and PDF
  29 and published on Readthedocs.io.
  30 The developer WiKi can reference these rendered documents directly allowing projects to
  31 easily maintain current release documentation.
  32 Read :ref:`this page <include-documentation>` which describes how documentation is created from
  33 ONAP Documentation project (doc) documentation source and other ONAP projects providing source material.
  34
  35 Licencing Your Documentation
  36 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  37 All contributions to the ONAP project are done in accordance with the ONAP licensing requirements.
  38 Documentation in ONAP is contributed
  39 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
  40 All documentation files need to be licensed using the text below. The license may be applied in the first lines of
  41 all contributed RST files:
  42
  43 .. code-block:: bash
  44
  45  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
  46  .. (c) <optionally add copywriters name>
  47
  48  These lines will not be rendered in the html and pdf files.
  49
  50 Storing Content Files in Your Repository
  51 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  52 All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory.
  53 The documentation toolchain will look in these directories and be triggered by events in repositories
  54 containing these directories.
  55 when generating documents.
  56
  57 .. index:: master, document
  58
  59 Document Structure and Contribution
  60 -----------------------------------
  61 A top level master_document structure is proposed for organizing and storing all documents.
  62 Four areas as shown below with some additional detail under each area.
  63 This structure may change some as we get the full requirements and gain experience with the first reelase of ONAP.
  64 Where multiple sections with similar content are expected, templates can be created and stored
  65 under `doc/docs/templates/`. For example each component providing release notes uses the same release-note template.
  66 A template is a directory name in `doc/docs/templates` and the directory contains at least an index.rst file with
  67 content and as needed references to other sources in the template directory.
  68
  69 Project teams are encouraged to reuse and if needed propose new templates to ensure that there is
  70 consistency across projects.
  71
  72 ::
  73
  74         docs/
  75         ├── release
  76         │   ├── overview
  77         │   ├── architecture
  78         │   ├── use-cases
  79         │   ├── tutorials
  80         │   └── release-notes
  81         ├── onap-developer
  82         │   ├── design
  83         │   ├── develop
  84         │   ├── document
  85         │   └── test
  86         ├── administrator
  87         │   ├── configure
  88         │   ├── deploy
  89         │   └── operate
  90         ├── service-designer
  91         │   ├── deploy
  92         │   ├── design
  93         │   └── portal
  94         └── vnf-provider
  95             ├── guidelines
  96             └── sdk
  97
  98
  99 Release Documentation
 100 ^^^^^^^^^^^^^^^^^^^^^
 101 Release documentation is the set of documents that are published for each ONAP release.
 102 The documents have a master index.rst file in the <doc> repository and reference content as needed
 103 from other project repository.
 104 To provide content for these other projects place <content>.rst files in a directory in your repository that
 105 matches the master document and add a reference to that file in the correct place in the
 106 corresponding master index.rst.
 107
 108 **Release Overview**: `doc/docs/release/overview`
 109
 110 - Content for this is prepared by the Marketing team together with the use case committee and doc project team.
 111 - This document is not a project contribution driven document.
 112
 113 **Installation Instruction**: `doc/docs/release/install`
 114
 115 - Document providing an introduction, order, and aggregation of release notes from other component projects.
 116 - This document is a contribution driven document.
 117
 118 **To Be Provided**: `<repo>/docs/xxxxxxxx`
 119
 120 - Additional descriptions for the above outline as it is finalized.
 121
 122