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 Introduction
   5 ============
   6 This guide describes how to create documentation for the Open Network
   7 Automation Platform (ONAP).  ONAP projects create a variety of document
   8 types depending on the nature of the project. Some projects will create
   9 detailed technical descriptions such as configuration parameters or how
  10 to use or extend the functionality of platform component.
  11 These descriptions may be used together as a reference for that project
  12 and/or be used in documents tailored to a specific user audience and
  13 task they are performing.
  14
  15 Much of the content in this document is derived from similar
  16 documentation processes used in other Linux Foundation
  17 Projects including OPNFV and Open Daylight.
  18
  19
  20 End to End View
  21 ---------------
  22 ONAP documentation is stored in git repositories, changes are managed
  23 with gerrit reviews, and published documents generated when there is a
  24 change in any source used to build the documentation.
  25
  26 Authors create source for documents in reStructured Text (RST) that is
  27 rendered to HTML and PDF and published on Readthedocs.io.
  28 The developer Wiki or other web sites can reference these rendered
  29 documents directly allowing projects to easily maintain current release
  30 documentation.
  31
  32
  33 Structure
  34 ---------
  35 A top level master_document structure is used to organize all
  36 documents for an ONAP release that reside in the doc git repository.
  37 Complete documents or guides may reside here and reference parts of
  38 source for documentation from other project repositories
  39 A starting structure is shown below and may change as content is
  40 intergrated for each release.   Others ONAP projects will provide
  41 content that is referenced from this structure.
  42
  43 .. index:: master
  44
  45
  46 ::
  47
  48         docs/
  49         ├── release
  50         │   ├── overview
  51         │   ├── architecture
  52         │   ├── use-cases
  53         │   ├── tutorials
  54         │   └── release-notes
  55         ├── onap-developer
  56         │   ├── design
  57         │   ├── develop
  58         │   ├── document
  59         │   └── test
  60         ├── adminstrator
  61         │   ├── configure
  62         │   ├── deploy
  63         │   └── operate
  64         ├── service-designer
  65         │   ├── deploy
  66         │   ├── design
  67         │   └── portal
  68         └── vnf-provider
  69             ├── guidelines
  70             └── sdk
  71
  72
  73
  74 Source Files
  75 ------------
  76 All documentation for a project should be structured and stored
  77 in or below `<your_project_repo>/docs/` directory as Restructured Text.
  78 ONAP jenkins jobs that verify and merge documentation are triggered by
  79 file changes in the docs directory and below.
  80
  81
  82 .. index:: licensing
  83
  84 Licencing
  85 ---------
  86 All contributions to the ONAP project are done in accordance with the
  87 ONAP licensing requirements.   Documentation in ONAP is contributed
  88 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
  89 All documentation files need to be licensed using the text below.
  90 The license may be applied in the first lines of all contributed RST
  91 files:
  92
  93 .. code-block:: bash
  94
  95  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
  96  .. (c) <optionally add copyrights company name>
  97
  98  These lines will not be rendered in the html and pdf files.
  99
 100
 101
 102 Templates
 103 ---------
 104 To encourage consistency of information across components, some
 105 templates are available as a starting point under `doc/docs/templates/`
 106 and listed below.  With the "show source" feature on html pages, you
 107 may be able to use portions of an existing page as starting point for
 108 creating new content.
 109
 110
 111 .. toctree::
 112    :maxdepth: 1
 113    :glob:
 114
 115    ../../../templates/**/index
 116