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