Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 1 | .. This work is licensed under a Creative Commons Attribution 4.0 International License. |
| 2 | |
| 3 | |
| 4 | Documentation Guide |
| 5 | =================== |
| 6 | |
| 7 | This page describes how documentation is created for the Open Network Automation Platform (ONAP). |
| 8 | ONAP projects create a variety of document types depending on the nature of the project. |
| 9 | Some projects will create detailed technical descriptions such as configuration parameters or how to |
| 10 | use or extend the functionality of platform component that may be used as a standalone reference for that project and/or |
| 11 | be used in larger end to end documents tailored to a specific user audience and task they are performing. |
| 12 | |
| 13 | Acknowledgement |
| 14 | --------------- |
| 15 | |
| 16 | Much of the content in this document is derived from similar documentation processes used in other Linux Foundation Projects |
| 17 | including OPNFV and Open Daylight. |
| 18 | |
| 19 | .. contents:: |
| 20 | :depth: 3 |
| 21 | :local: |
| 22 | |
| 23 | Getting Started |
| 24 | --------------- |
| 25 | ONAP documentation is stored in git repositories, changes are managed with gerrit reviews, and published documents |
| 26 | automatically generated when there is a change in any source used to build the documentation. |
| 27 | |
| 28 | Authors create source for documents in reStructured Text (RST) that is automatically rendered to HTML and PDF |
| 29 | and published on Readthedocs.io. |
| 30 | The developer WiKi can reference these rendered documents directly allowing projects to |
| 31 | easily maintain current release documentation. |
| 32 | Read :ref:`this page <include-documentation>` which describes how documentation is created from |
| 33 | ONAP Documentation project (doc) documentation source and other ONAP projects providing source material. |
| 34 | |
| 35 | Licencing Your Documentation |
| 36 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 37 | All contributions to the ONAP project are done in accordance with the ONAP licensing requirements. |
| 38 | Documentation in ONAP is contributed |
| 39 | in accordance with the `Creative Commons 4.0 <https://creativecommons.org/licenses/by/4.0/>`_ license. |
| 40 | All documentation files need to be licensed using the text below. The license may be applied in the first lines of |
| 41 | all contributed RST files: |
| 42 | |
| 43 | .. code-block:: bash |
| 44 | |
| 45 | .. This work is licensed under a Creative Commons Attribution 4.0 International License. |
| 46 | .. (c) <optionally add copywriters name> |
| 47 | |
| 48 | These lines will not be rendered in the html and pdf files. |
| 49 | |
| 50 | Storing Content Files in Your Repository |
| 51 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 52 | All documentation for your project should be structured and stored in `<your_project_repo>/docs/` directory. |
| 53 | The documentation toolchain will look in these directories and be triggered by events in repositories |
| 54 | containing these directories. |
| 55 | when generating documents. |
| 56 | |
Rich Bennett | d1f0949 | 2017-07-25 19:28:00 -0400 | [diff] [blame^] | 57 | .. index:: master, document |
| 58 | |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 59 | Document Structure and Contribution |
| 60 | ----------------------------------- |
Rich Bennett | d1f0949 | 2017-07-25 19:28:00 -0400 | [diff] [blame^] | 61 | A top level master_document structure is proposed for organizing and storing all documents. |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 62 | Four areas as shown below with some additional detail under each area. |
| 63 | This structure may change some as we get the full requirements and gain experience with the first reelase of ONAP. |
| 64 | Where multiple sections with similar content are expected, templates can be created and stored |
| 65 | under `doc/docs/templates/`. For example each component providing release notes uses the same release-note template. |
| 66 | A template is a directory name in `doc/docs/templates` and the directory contains at least an index.rst file with |
| 67 | content and as needed references to other sources in the template directory. |
| 68 | |
| 69 | Project teams are encouraged to reuse and if needed propose new templates to ensure that there is |
| 70 | consistency across projects. |
| 71 | |
| 72 | :: |
| 73 | |
| 74 | docs/ |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 75 | ├── release |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 76 | │ ├── overview |
Rich Bennett | d1f0949 | 2017-07-25 19:28:00 -0400 | [diff] [blame^] | 77 | │ ├── architecture |
| 78 | │ ├── use-cases |
| 79 | │ ├── tutorials |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 80 | │ └── release-notes |
Rich Bennett | d1f0949 | 2017-07-25 19:28:00 -0400 | [diff] [blame^] | 81 | ├── onap-developer |
| 82 | │ ├── design |
| 83 | │ ├── develop |
| 84 | │ ├── document |
| 85 | │ └── test |
| 86 | ├── administrator |
| 87 | │ ├── configure |
| 88 | │ ├── deploy |
| 89 | │ └── operate |
Rich Bennett | ac93e0e | 2017-07-19 01:36:52 -0400 | [diff] [blame] | 90 | ├── service-designer |
| 91 | │ ├── deploy |
| 92 | │ ├── design |
| 93 | │ └── portal |
| 94 | └── vnf-provider |
| 95 | ├── guidelines |
| 96 | └── sdk |
| 97 | |
| 98 | |
| 99 | Release Documentation |
| 100 | ^^^^^^^^^^^^^^^^^^^^^ |
| 101 | Release documentation is the set of documents that are published for each ONAP release. |
| 102 | The documents have a master index.rst file in the <doc> repository and reference content as needed |
| 103 | from other project repository. |
| 104 | To provide content for these other projects place <content>.rst files in a directory in your repository that |
| 105 | matches the master document and add a reference to that file in the correct place in the |
| 106 | corresponding master index.rst. |
| 107 | |
| 108 | **Release Overview**: `doc/docs/release/overview` |
| 109 | |
| 110 | - Content for this is prepared by the Marketing team together with the use case committee and doc project team. |
| 111 | - This document is not a project contribution driven document. |
| 112 | |
| 113 | **Installation Instruction**: `doc/docs/release/install` |
| 114 | |
| 115 | - Document providing an introduction, order, and aggregation of release notes from other component projects. |
| 116 | - This document is a contribution driven document. |
| 117 | |
| 118 | **To Be Provided**: `<repo>/docs/xxxxxxxx` |
| 119 | |
| 120 | - Additional descriptions for the above outline as it is finalized. |
| 121 | |
| 122 | |