X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fguide%2Fonap-developer%2Fhow-to-use-docs%2Fdocumentation-guide.rst;h=6bce35df9ca113da73c9a1a57fae3d71572bf355;hb=1da304689093f1144d2be5cfb1fac6f29a158caa;hp=5dc3d714ebfa114e6cdeff34caa343f48e29d043;hpb=d1f094919f1558d05f5aa72e209ad9359135bcf4;p=doc.git diff --git a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst index 5dc3d714e..6bce35df9 100644 --- a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst +++ b/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst @@ -1,73 +1,47 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -Documentation Guide -=================== - -This page describes how documentation is created 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 that may be used as a standalone reference for that project and/or -be used in larger end to end documents tailored to a specific user audience and task they are performing. - -Acknowledgement +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. -Much of the content in this document is derived from similar documentation processes used in other Linux Foundation Projects -including OPNFV and Open Daylight. - -.. contents:: - :depth: 3 - :local: - -Getting Started ---------------- -ONAP documentation is stored in git repositories, changes are managed with gerrit reviews, and published documents -automatically 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 automatically rendered to HTML and PDF -and published on Readthedocs.io. -The developer WiKi can reference these rendered documents directly allowing projects to -easily maintain current release documentation. -Read :ref:`this page ` which describes how documentation is created from -ONAP Documentation project (doc) documentation source and other ONAP projects providing source material. - -Licencing Your Documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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 `_ 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: +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. -.. code-block:: bash - - .. This work is licensed under a Creative Commons Attribution 4.0 International License. - .. (c) - - These lines will not be rendered in the html and pdf files. -Storing Content Files in Your Repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All documentation for your project should be structured and stored in `/docs/` directory. -The documentation toolchain will look in these directories and be triggered by events in repositories -containing these directories. -when generating documents. +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, document +.. index:: master -Document Structure and Contribution ------------------------------------ -A top level master_document structure is proposed for organizing and storing all documents. -Four areas as shown below with some additional detail under each area. -This structure may change some as we get the full requirements and gain experience with the first reelase of ONAP. -Where multiple sections with similar content are expected, templates can be created and stored -under `doc/docs/templates/`. For example each component providing release notes uses the same release-note template. -A template is a directory name in `doc/docs/templates` and the directory contains at least an index.rst file with -content and as needed references to other sources in the template directory. - -Project teams are encouraged to reuse and if needed propose new templates to ensure that there is -consistency across projects. :: @@ -83,7 +57,7 @@ consistency across projects. │ ├── develop │ ├── document │ └── test - ├── administrator + ├── adminstrator │ ├── configure │ ├── deploy │ └── operate @@ -96,27 +70,47 @@ consistency across projects. └── sdk -Release Documentation -^^^^^^^^^^^^^^^^^^^^^ -Release documentation is the set of documents that are published for each ONAP release. -The documents have a master index.rst file in the repository and reference content as needed -from other project repository. -To provide content for these other projects place .rst files in a directory in your repository that -matches the master document and add a reference to that file in the correct place in the -corresponding master index.rst. -**Release Overview**: `doc/docs/release/overview` +Source Files +------------ +All documentation for a project should be structured and stored +in or below `/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 `_ 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 -- Content for this is prepared by the Marketing team together with the use case committee and doc project team. -- This document is not a project contribution driven document. + .. This work is licensed under a Creative Commons Attribution 4.0 International License. + .. (c) + + These lines will not be rendered in the html and pdf files. -**Installation Instruction**: `doc/docs/release/install` -- Document providing an introduction, order, and aggregation of release notes from other component projects. -- This document is a contribution driven document. -**To Be Provided**: `/docs/xxxxxxxx` +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. -- Additional descriptions for the above outline as it is finalized. +.. toctree:: + :maxdepth: 1 + :glob: + ../../../templates/**/index +