docs/guides/onap-developer/how-to-use-docs/introduction.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0
   2 .. International License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
   4
   5 Introduction
   6 ============
   7 This guide describes how to create documentation for the Open Network
   8 Automation Platform (ONAP).  ONAP projects create a variety of
   9 content depending on the nature of the project.  For example projects
  10 delivering a platform component may have different types of content than
  11 a project that creates libraries for a software development kit.
  12 The content from each project may be used together as a reference for
  13 that project and/or be used in documents that are tailored to a specific
  14 user audience and tasks they are performing.
  15
  16 Much of the content in this document is derived from similar
  17 documentation processes used in other Linux Foundation
  18 Projects including OPNFV and Open Daylight.
  19
  20 Why reStructuredText/Sphinx?
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22
  23 In the past, standard documentation methods included ad-hoc Word documents,
  24 PDFs, poorly organized Wikis, and other, often closed, tools like
  25 Adobe FrameMaker.  The rise of DevOps, Agile, and Continuous Integration,
  26 however, created a paradigm shift for those who care about documentation
  27 because:
  28
  29 1. Documentation must be tightly coupled with code/product releases.
  30    In many cases, particularly with open-source products, many different
  31    versions of the same code can be installed in various production
  32    environments. DevOps personnel must have access to the correct version
  33    of documentation.
  34
  35 2. Resources are often tight, volunteers scarce. With a large software base
  36    like ONAP, a small team of technical writers, even if they are also
  37    developers, cannot keep up with a constantly changing, large code base.
  38    Therefore, those closest to the code should document it as best they can,
  39    and let professional writers edit for style, grammar, and consistency.
  40
  41 Plain-text formatting syntaxes, such as reStructuredText, Markdown,
  42 and Textile, are a good choice for documentation because:
  43
  44 a. They are editor agnostic
  45
  46 b. The source is nearly as easy to read as the rendered text
  47
  48 c. Documentation can be treated exactly as source code is (e.g. versioned,
  49    diff'ed, associated with commit messages that can be included
  50    in rendered docs)
  51
  52 d. Shallow learning curve
  53
  54 The documentation team chose reStructuredText largely because of Sphinx,
  55 a Python-based documentation build system, which uses reStructuredText
  56 natively. In a code base as large as ONAP's, cross-referencing between
  57 component documentation was deemed critical. Sphinx and reStructuredText
  58 have built-in functionality that makes collating and cross-referencing
  59 component documentation easier.
  60
  61 Which docs should go where?
  62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  63
  64 Frequently, developers ask where documentation should be created. Should
  65 they always use reStructuredText/Sphinx? Not necessarily. Is the wiki
  66 appropriate for anything at all? Yes.
  67
  68 It's really up to the development team. Here is a simple rule:
  69
  70 The more tightly coupled the documentation is to a particular version
  71 of the code, the more likely it is that it should be stored with the
  72 code in reStructuredText.
  73
  74 The doc team encourages component teams to store as much documentation
  75 as reStructuredText as possible because:
  76
  77 1. It is easier to edit component documentation for grammar,
  78    spelling, clarity, and consistency.
  79
  80 2. A consistent formatting syntax across components will allow
  81    flexibility in producing different kinds of output.
  82
  83 3. It is easier to re-organize the documentation.
  84
  85 4. Wiki articles tend to grow in size and not maintained making it hard
  86    to find current information.
  87
  88 Structure
  89 ---------
  90 A top level master document structure is used to organize all
  91 documents created by ONAP projects and this resides in the gerrit doc
  92 repository.  Complete documents or guides may reside here and
  93 reference parts of source for documentation from other project
  94 repositories.  Other ONAP projects will provide content that
  95 is referenced from this structure.
  96
  97 ::
  98
  99 docs
 100 ├── guides
 101 │   ├── active-projects
 102 │   ├── onap-developer
 103 │   │   ├── apiref
 104 │   │   ├── architecture
 105 │   │   │   └── media
 106 │   │   ├── developing
 107 │   │   ├── how-to-use-docs
 108 │   │   ├── tutorials
 109 │   │   └── use-cases
 110 │   ├── onap-operator
 111 │   │   ├── cloud_site
 112 │   │   │   ├── aws
 113 │   │   │   ├── azure
 114 │   │   │   ├── k8s
 115 │   │   │   ├── openstack
 116 │   │   │   └── vmware
 117 │   │   ├── onap-portal-admin
 118 │   │   │   └── attachments
 119 │   │   └── settingup
 120 │   ├── onap-provider
 121 │   ├── onap-user
 122 │   │   ├── configure
 123 │   │   │   ├── change_config
 124 │   │   │   ├── pnf_connect
 125 │   │   │   └── vnf_connect
 126 │   │   ├── design
 127 │   │   │   ├── control-loop
 128 │   │   │   │   └── media
 129 │   │   │   ├── media
 130 │   │   │   ├── parameter_resolution
 131 │   │   │   │   └── ubuntu_example
 132 │   │   │   │       ├── cba-after-enrichment
 133 │   │   │   │       │   ├── Definitions
 134 │   │   │   │       │   ├── Templates
 135 │   │   │   │       │   └── TOSCA-Metadata
 136 │   │   │   │       ├── cba-before-enrichment
 137 │   │   │   │       │   ├── Definitions
 138 │   │   │   │       │   ├── Templates
 139 │   │   │   │       │   └── TOSCA-Metadata
 140 │   │   │   │       └── ubuntuCDS_heat
 141 │   │   │   ├── pre-onboarding
 142 │   │   │   │   └── media
 143 │   │   │   ├── resource-onboarding
 144 │   │   │   │   └── media
 145 │   │   │   ├── service-design
 146 │   │   │   │   └── media
 147 │   │   │   ├── service-distribution
 148 │   │   │   │   └── media
 149 │   │   │   └── vfcreation
 150 │   │   │       └── media
 151 │   │   ├── instantiate
 152 │   │   │   ├── instantiation
 153 │   │   │   │   ├── nbi
 154 │   │   │   │   ├── pnf_instance
 155 │   │   │   │   ├── service_instance
 156 │   │   │   │   ├── so1
 157 │   │   │   │   ├── so2
 158 │   │   │   │   ├── uui
 159 │   │   │   │   ├── vid
 160 │   │   │   │   ├── virtual_link_instance
 161 │   │   │   │   └── vnf_instance
 162 │   │   │   └── pre_instantiation
 163 │   │   └── onap-portal-user
 164 │   │       └── attachments
 165 │   └── overview
 166 │       └── media
 167 ├── release
 168 ├── templates
 169 │   ├── collections
 170 │   └── sections
 171 └── use-cases
 172
 173
 174 Source Files
 175 ------------
 176 All documentation for project repositories should be structured and stored
 177 in or below `<your_project_repo>/docs/` directory as Restructured Text.
 178 ONAP jenkins jobs that verify and merge documentation are triggered by
 179 RST file changes in the top level docs directory and below.
 180
 181 Licensing
 182 ---------
 183 All contributions to the ONAP project are done in accordance with the
 184 ONAP licensing requirements.   Documentation in ONAP is contributed
 185 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
 186 All documentation files need to be licensed using the text below.
 187 The license may be applied in the first lines of all contributed RST
 188 files:
 189
 190 .. code-block:: bash
 191
 192  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 193  .. http://creativecommons.org/licenses/by/4.0
 194  .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL
 195
 196  These lines will not be rendered in the html and pdf files.
 197
 198 When there are subsequent, significant contributions to a source file
 199 from a different contributor, a new copyright line may be appended
 200 after the last existing copyright line.