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