docs/guides/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
   8 content depending on the nature of the project.  For example projects delivering
   9 a platform component may have different types of content than
  10 a project that creates libraries for a software development kit.
  11 The content from each project may be used together as a reference for that project
  12 and/or be used in documents are 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 Why reStructuredText/Sphinx?
  33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  34
  35 In the past, standard documentation methods included ad-hoc Word documents, PDFs,
  36 poorly organized Wikis, and other, often closed, tools like Adobe FrameMaker.
  37 The rise of DevOps, Agile, and Continuous Integration, however, created a paradigm
  38 shift for those who care about documentation because:
  39
  40 1. Documentation must be tightly coupled with code/product releases. In many cases,
  41 particularly with open-source products, many different versions of the same code
  42 can be installed in various production environments. DevOps personnel must have
  43 access to the correct version of documentation.
  44
  45 2. Resources are often tight, volunteers scarce. With a large software base
  46 like ONAP, a small team of technical writers, even if they are also developers,
  47 cannot keep up with a constantly changing, large code base. Therefore, those closest
  48 to the code should document it as best they can, and let professional writers edit for
  49 style, grammar, and consistency.
  50
  51 Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile,
  52 are a good choice for documentation because:
  53
  54 a. They are editor agnostic
  55 b. The source is nearly as easy to read as the rendered text
  56 c. Documentation can be treated exactly as source code is (e.g. versioned,
  57    diff'ed, associated with commit messages that can be included in rendered docs)
  58 d. Shallow learning curve
  59
  60 The documentation team chose reStructuredText largely because of Sphinx, a Python-based
  61 documentation build system, which uses reStructuredText natively. In a code base
  62 as large as ONAP's, cross-referencing between component documentation was deemed
  63 critical. Sphinx and reStructuredText have built-in functionality that makes
  64 collating and cross-referencing component documentation easier.
  65
  66 Which docs should go where?
  67 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  68
  69 Frequently, developers ask where documentation should be created. Should they always use
  70 reStructuredText/Sphinx? Not necessarily. Is the wiki appropriate for anything at all? Yes.
  71
  72 It's really up to the development team. Here is a simple rule:
  73
  74 The more tightly coupled the documentation is to a particular version of the code,
  75 the more likely it is that it should be stored with the code in reStructuredText.
  76
  77 Two examples on opposite ends of the spectrum:
  78
  79 Example 1: API documentation is often stored literally as code in the form of formatted
  80 comment sections. This would be an ideal choice for reStructuredText stored in a doc repo.
  81
  82 Example 2: A high-level document that describes in general how a particular component interacts
  83 with other ONAP components with charts. The wiki would be a better choice for this.
  84
  85 The doc team encourages component teams to store as much documentation as reStructuredText
  86 as possible because:
  87
  88 1. The doc team can more easily edit component documentation for grammar, spelling, clarity, and consistency.
  89 2. A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output.
  90 3. The doc team can easily re-organize the documentation.
  91 4. Wiki articles tend to grow stale over time as the people who write them change positions or projects.
  92
  93 Structure
  94 ---------
  95 A top level master document structure is used to organize all
  96 documents for an ONAP release and this resides in the gerrit doc repository.
  97 Complete documents or guides may reside here and reference parts of
  98 source for documentation from other project repositories
  99 A starting structure is shown below and may change as content is
 100 integrated for each release.   Other ONAP projects will provide
 101 content that is referenced from this structure.
 102
 103 .. index:: master
 104
 105
 106 ::
 107
 108         docs/
 109         ├── releases
 110         │   ├── major releases
 111         │   ├── projects
 112         │   ├── cryptographic signatures
 113         │   └── references
 114         ├── onap-developer
 115         │   ├── architecture
 116         │   ├── tutorials
 117         │   ├── setting up
 118         │   ├── developing
 119         │   └── documenting
 120         └── onap-users
 121             ├── vf provider
 122             ├── service designer
 123             ├── service administrator
 124             └── platform administrator
 125
 126
 127
 128 Source Files
 129 ------------
 130 All documentation for a project should be structured and stored
 131 in or below `<your_project_repo>/docs/` directory as Restructured Text.
 132 ONAP jenkins jobs that verify and merge documentation are triggered by
 133 RST file changes in the top level docs directory and below.
 134
 135
 136 .. index:: licensing
 137
 138 Licensing
 139 ---------
 140 All contributions to the ONAP project are done in accordance with the
 141 ONAP licensing requirements.   Documentation in ONAP is contributed
 142 in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license.
 143 All documentation files need to be licensed using the text below.
 144 The license may be applied in the first lines of all contributed RST
 145 files:
 146
 147 .. code-block:: bash
 148
 149  .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 150  .. http://creativecommons.org/licenses/by/4.0
 151  .. Copyright YEAR ONAP or COMPANY or INDIVIDUAL
 152
 153  These lines will not be rendered in the html and pdf files.
 154
 155 When there are subsequent, significant contributions to a source file from a different contributor,
 156 a new copyright line may be appended after the last existing copyright line.
 157