diff options
Diffstat (limited to 'docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst')
| -rw-r--r-- | docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst | 58 |
1 files changed, 26 insertions, 32 deletions
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..380b05cce 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 @@ -7,8 +7,9 @@ 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. +use or extend the functionality of platform component. +These descriptions may be together as a reference for that project and/or +be used in documents tailored to a specific user audience and task they are performing. Acknowledgement --------------- @@ -27,7 +28,7 @@ automatically generated when there is a change in any source used to build the d 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 +The developer Wiki can reference these rendered documents directly allowing projects to easily maintain current release documentation. Read :ref:`this page <include-documentation>` which describes how documentation is created from ONAP Documentation project (doc) documentation source and other ONAP projects providing source material. @@ -50,24 +51,16 @@ all contributed RST files: Storing Content Files in Your Repository ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory. -The documentation toolchain will look in these directories and be triggered by events in repositories -containing these directories. -when generating documents. +The documentation tool chain will look in these directories when triggered by verify and merge events. .. index:: master, document 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. +A top level master_document structure is proposed for organizing all documents +in the four areas as shown below with additional detail under each area. +This structure may change as we gain experience with the first release of ONAP. -Project teams are encouraged to reuse and if needed propose new templates to ensure that there is -consistency across projects. :: @@ -83,7 +76,7 @@ consistency across projects. │ ├── develop │ ├── document │ └── test - ├── administrator + ├── adminstrator │ ├── configure │ ├── deploy │ └── operate @@ -95,28 +88,29 @@ consistency across projects. ├── guidelines └── sdk +Templates +^^^^^^^^^ +Where multiple sections with similar content are expected, templates can be created and stored +under `doc/docs/templates/` and used a starting point for similar content. +For example the high level architecture and interface information for an ONAP component. +A template is a directory name in `doc/docs/templates` , the directory contains at least an +index.rst file with a starting point for creating content, and as needed +references to other sources in the template directory. Current templates are shown below. + +.. toctree:: + :maxdepth: 1 + + ../../../templates/index + +Project teams are encouraged to reuse and propose new templates for reuse. 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 <doc> repository and reference content as needed from other project repository. -To provide content for these other projects place <content>.rst files in a directory in your repository that +To provide content for these other projects place <content>.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` - -- 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. - -**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**: `<repo>/docs/xxxxxxxx` - -- Additional descriptions for the above outline as it is finalized. - - |