docs/guides/onap-developer/how-to-use-docs/documentation-guide.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 are tailored to a specific
  14 user audience and task 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
  21 End to End View
  22 ---------------
  23 ONAP documentation is stored in git repositories, changes are managed
  24 with gerrit reviews, and published documents generated when there is a
  25 change in any source used to build the documentation.
  26
  27 Authors create source for documents in reStructured Text (RST) that is
  28 rendered to HTML and PDF and published on Readthedocs.io.
  29 The developer Wiki or other web sites can reference these rendered
  30 documents directly allowing projects to easily maintain current release
  31 documentation.
  32
  33 Why reStructuredText/Sphinx?
  34 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35
  36 In the past, standard documentation methods included ad-hoc Word documents,
  37 PDFs, poorly organized Wikis, and other, often closed, tools like
  38 Adobe FrameMaker.  The rise of DevOps, Agile, and Continuous Integration,
  39 however, created a paradigm shift for those who care about documentation
  40 because:
  41
  42 1. Documentation must be tightly coupled with code/product releases.
  43    In many cases, particularly with open-source products, many different
  44    versions of the same code can be installed in various production
  45    environments. DevOps personnel must have access to the correct version
  46    of documentation.
  47
  48 2. Resources are often tight, volunteers scarce. With a large software base
  49    like ONAP, a small team of technical writers, even if they are also
  50    developers, cannot keep up with a constantly changing, large code base.
  51    Therefore, those closest to the code should document it as best they can,
  52    and let professional writers edit for style, grammar, and consistency.
  53
  54 Plain-text formatting syntaxes, such as reStructuredText, Markdown,
  55 and Textile, are a good choice for documentation because:
  56
  57 a. They are editor agnostic
  58
  59 b. The source is nearly as easy to read as the rendered text
  60
  61 c. Documentation can be treated exactly as source code is (e.g. versioned,
  62    diff'ed, associated with commit messages that can be included
  63    in rendered docs)
  64
  65 d. Shallow learning curve
  66
  67 The documentation team chose reStructuredText largely because of Sphinx,
  68 a Python-based documentation build system, which uses reStructuredText
  69 natively. In a code base as large as ONAP's, cross-referencing between
  70 component documentation was deemed critical. Sphinx and reStructuredText
  71 have built-in functionality that makes collating and cross-referencing
  72 component documentation easier.
  73
  74 Which docs should go where?
  75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  76
  77 Frequently, developers ask where documentation should be created. Should
  78 they always use reStructuredText/Sphinx? Not necessarily. Is the wiki
  79 appropriate for anything at all? Yes.
  80
  81 It's really up to the development team. Here is a simple rule:
  82
  83 The more tightly coupled the documentation is to a particular version
  84 of the code, the more likely it is that it should be stored with the
  85 code in reStructuredText.
  86
  87 The doc team encourages component teams to store as much documentation
  88 as reStructuredText as possible because:
  89
  90 1. It is easier to edit component documentation for grammar,
  91    spelling, clarity, and consistency.
  92
  93 2. A consistent formatting syntax across components will allow
  94    flexibility in producing different kinds of output.
  95
  96 3. It is easier to re-organize the documentation.
  97
  98 4. Wiki articles tend to grow in size and not maintained making it hard
  99    to find current information.
 100
 101 Structure
 102 ---------
 103 A top level master document structure is used to organize all
 104 documents created by ONAP projects and this resides in the gerrit doc
 105 repository.  Complete documents or guides may reside here and
 106 reference parts of source for documentation from other project
 107 repositories.  Other ONAP projects will provide content that
 108 is referenced from this structure.
 109
 110 ::
 111
 112     docs/
 113     ├── guides
 114     │   ├── onap-developer
 115     │   │   ├── apiref
 116     │   │   ├── architecture
 117     │   │   ├── developing
 118     │   │   ├── how-to-use-docs
 119     │   │   ├── settingup
 120     │   │   └── tutorials
 121     │   └── onap-user
 122     │       ├── onap-portal
 123     │       ├── platform operations
 124     │       ├── service design
 125     │       ├── service deployment
 126     │       ├── vnf provider
 127     │       └── vnf certifier
 128     ├── release
 129     ├── templates
 130     │   ├── collections
 131     │   └── sections
 132     └── use-cases
 133
 134
 135 Source Files
 136 ------------
 137 All documentation for project repositories should be structured and stored
 138 in or below `<your_project_repo>/docs/` directory as Restructured Text.
 139 ONAP jenkins jobs that verify and merge documentation are triggered by
 140 RST file changes in the top level docs directory and below.
 141
 142 Licensing
 143 ---------
 144 All contributions to the ONAP project are done in accordance with the
 145 ONAP licensing requirements.   Documentation in ONAP is contributed
 146 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
 147 All documentation files need to be licensed using the text below.
 148 The license may be applied in the first lines of all contributed RST
 149 files:
 150
 151 .. code-block:: bash
 152
 153  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 154  .. http://creativecommons.org/licenses/by/4.0
 155  .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL
 156
 157  These lines will not be rendered in the html and pdf files.
 158
 159 When there are subsequent, significant contributions to a source file
 160 from a different contributor, a new copyright line may be appended
 161 after the last existing copyright line.
 162