docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst - onap/doc - Gitiles

 .. 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.

 Why reStructuredText/Sphinx?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 In the past, standard documentation methods included ad-hoc Word documents, PDFs,
 poorly organized Wikis, and other, often closed, tools like Adobe FrameMaker.
 The rise of DevOps, Agile, and Continuous Integration, however, created a paradigm
 shift for those who care about documentation because:

 1. Documentation must be tightly coupled with code/product releases. In many cases,
 particularly with open-source products, many different versions of the same code
 can be installed in various production environments. DevOps personnel must have
 access to the correct version of documentation.

 2. Resources are often tight, volunteers scarce. With a large software base
 like ONAP, a small team of technical writers, even if they are also developers,
 cannot keep up with a constantly changing, large code base. Therefore, those closest
 to the code should document it as best they can, and let professional writers edit for
 style, grammar, and consistency.

 Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile,
 are a good choice for documentation because:
   a. They are editor agnostic
   b. The source is nearly as easy to read as the rendered text
   c. Documentation can be treated exactly as source code is (e.g. versioned,
 diff'ed, associated with commit messages that can be included in rendered docs)
   d. Shallow learning curve

 The documentation team chose reStructuredText largely because of Sphinx, a Python-based
 documentation build system, which uses reStructuredText natively. In a code base
 as large as ONAP's, cross-referencing between component documentation was deemed
 critical. Sphinx and reStructuredText have built-in functionality that makes
 collating and cross-referencing component documentation easier.

 Which docs should go where?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Frequently, developers ask where documentation should be created. Should they always use
 reStructuredText/Sphinx? Not necessarily. Is the wiki appropriate for anything at all? Yes.

 It's really up to the development team. Here is a simple rule:

 The more tightly coupled the documentation is to a particular version of the code,
 the more likely it is that it should be stored with the code in reStructuredText.

 Two examples on opposite ends of the spectrum:

 Example 1: API documentation is often stored literally as code in the form of formatted
 comment sections. This would be an ideal choice for reStructuredText stored in a doc repo.

 Example 2: A high-level document that describes in general how a particular component interacts
 with other ONAP components with charts. The wiki would be a better choice for this.

 The doc team encourages component teams to store as much documentation as reStructuredText
 as possible because:

 1. The doc team can more easily edit component documentation for grammar, spelling, clarity, and consistency.
 2. A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output.
 3. The doc team can easily re-organize the documentation.
 4. Wiki articles tend to grow stale over time as the people who write them change positions or projects.

 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
	.. 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.

	Why reStructuredText/Sphinx?
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	In the past, standard documentation methods included ad-hoc Word documents, PDFs,
	poorly organized Wikis, and other, often closed, tools like Adobe FrameMaker.
	The rise of DevOps, Agile, and Continuous Integration, however, created a paradigm
	shift for those who care about documentation because:

	1. Documentation must be tightly coupled with code/product releases. In many cases,
	particularly with open-source products, many different versions of the same code
	can be installed in various production environments. DevOps personnel must have
	access to the correct version of documentation.

	2. Resources are often tight, volunteers scarce. With a large software base
	like ONAP, a small team of technical writers, even if they are also developers,
	cannot keep up with a constantly changing, large code base. Therefore, those closest
	to the code should document it as best they can, and let professional writers edit for
	style, grammar, and consistency.

	Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile,
	are a good choice for documentation because:
	a. They are editor agnostic
	b. The source is nearly as easy to read as the rendered text
	c. Documentation can be treated exactly as source code is (e.g. versioned,
	diff'ed, associated with commit messages that can be included in rendered docs)
	d. Shallow learning curve

	The documentation team chose reStructuredText largely because of Sphinx, a Python-based
	documentation build system, which uses reStructuredText natively. In a code base
	as large as ONAP's, cross-referencing between component documentation was deemed
	critical. Sphinx and reStructuredText have built-in functionality that makes
	collating and cross-referencing component documentation easier.

	Which docs should go where?
	~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Frequently, developers ask where documentation should be created. Should they always use
	reStructuredText/Sphinx? Not necessarily. Is the wiki appropriate for anything at all? Yes.

	It's really up to the development team. Here is a simple rule:

	The more tightly coupled the documentation is to a particular version of the code,
	the more likely it is that it should be stored with the code in reStructuredText.

	Two examples on opposite ends of the spectrum:

	Example 1: API documentation is often stored literally as code in the form of formatted
	comment sections. This would be an ideal choice for reStructuredText stored in a doc repo.

	Example 2: A high-level document that describes in general how a particular component interacts
	with other ONAP components with charts. The wiki would be a better choice for this.

	The doc team encourages component teams to store as much documentation as reStructuredText
	as possible because:

	1. The doc team can more easily edit component documentation for grammar, spelling, clarity, and consistency.
	2. A consistent formatting syntax across components will allow the doc team more flexibility in producing different kinds of output.
	3. The doc team can easily re-organize the documentation.
	4. Wiki articles tend to grow stale over time as the people who write them change positions or projects.

	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