diff options
Diffstat (limited to 'docs/guide/onap-developer/how-to-use-docs')
4 files changed, 79 insertions, 76 deletions
diff --git a/docs/guide/onap-developer/how-to-use-docs/addendum.rst b/docs/guide/onap-developer/how-to-use-docs/addendum.rst index ee0e5f24e..f97541730 100644 --- a/docs/guide/onap-developer/how-to-use-docs/addendum.rst +++ b/docs/guide/onap-developer/how-to-use-docs/addendum.rst @@ -4,7 +4,7 @@ Addendum ======== Index File -========== +---------- The index file must relatively reference your other rst files in that directory. @@ -23,7 +23,7 @@ Here is an example index.rst : documentation-example Source Files -============ +------------ Document source files have to be written in reStructuredText format (rst). Each file would be build as an html page. @@ -45,7 +45,7 @@ Here is an example source rst file : Hello! Writing RST Markdown -==================== +-------------------- See http://sphinx-doc.org/rest.html . @@ -59,22 +59,25 @@ You can add html content that only appears in html output by using the .. only:: html This line will be shown only in html version. +Jenkins Jobs +------------ + Verify Job ----------- +++++++++++ -The verify job name is **docs-verify-rtd-{branch}**. +The verify job name is **doc-{stream}-verify-rtd** -When you send document changes to gerrit, jenkins will create your documents -in HTML formats (normal and single-page) to verify that new document can be -built successfully. Please check the jenkins log and artifact carefully. -You can improve your document even if the build job succeeded. +Proposed changes in doc or any other repository that has been added as a +git submodule will be verified by this job prior to a gerrit code review. +Please check the Jenkins log carefully for warnings. +You can improve your document even if the verify job succeeded. Merge Job ----------- ++++++++++ -The merge job name is **docs-merge-rtd-{branch}**. +The merge job name is **doc-{stream}-merge-rtd**. -Once the patch is merged, jenkins will automatically trigger building of +When a committer merges a patch, Jenkins will automatically trigger building of the new documentation. This might take about 15 minutes while readthedocs -builds the documentatation. The newly built documentation shall show up +builds the documentation. The newly built documentation shall show up as appropriate placed in docs.onap.org/{branch}/path-to-file. 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. - - diff --git a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst index 8fa689fe4..3471ac1ec 100644 --- a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst +++ b/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst @@ -14,21 +14,25 @@ In your project repository -------------------------- Add your documentation to your repository in the folder structure and -using templates as described above. The documentation templates -are available in `doc/docs/templates/`, you should -copy the relevant templates to your <repo>/docs/ directory in your repository. -For instance if you want to document release-notes, then your steps shall be +using templates as described above. +When using a template, copy the directory in `doc/docs/templates/`, +to your <repo>/docs/ directory in your repository. +For instance if you want to document component-info, then your steps shall be as follows: .. code-block:: bash git clone ssh://<your_id>@gerrit.onap.org:29418/doc - cp -p doc/docs/templates/release-notes <your_repo>/docs/release-notes/ + cp -p doc/docs/templates/component-info <your_repo>/docs/component-info/ -You should then add the relevant information to the template that will -explain the documentation. When you are done writing, you can commit +You should then add the relevant information to the template. +When you are done writing, you can commit the documentation to the your project repository. +The sequence below shows basic git/gerrit steps, +see `Developer Best Practices`_ for complete current information. + +.. _Developer Best Practices: https://wiki.onap.org/x/BZZk .. code-block:: bash @@ -40,17 +44,17 @@ In the ONAP doc Repository -------------------------- To import project documents from project repositories, we use git submodules. -Each ONAP project providing documentation, other than the doc project, is loaded under `doc/docs/submodules/` -when needed for validating or publishing documentation. To describe the relationship between content files -we use the `Sphinx toctree directive`. +Each ONAP project providing documentation, other than the doc project, is loaded under +`doc/docs/submodules/` when needed for validating or publishing documentation. +To describe the relationship between content files we use the `Sphinx toctree directive`. The following diagram illustrates: - all ONAP gerrit project repositories, - - the doc project repository including a main index.rst, - - other master document directories and/or RST files that may be created to organize sections and documents, - - the submodules directory where other repositories and directories/files may be referenced, - - the templates directory with one example, a release-notes template, and - - another project repository `appc` that provides documentation source by copying and filling in an instance of the release-notes template. + - the doc project repository including a master document index.rst, + - other document directories and/or RST files that organize sections and documents doc repository, + - the submodules directory where other project repositories and directories/files may be referenced, + - the templates directory with one example, a component-info template that may referenced in release orhigh level design documents, and + - another project repository example, `appc` that provides documentation source by copying and filling in an instance of the component-info template. .. graphviz:: @@ -61,7 +65,7 @@ The following diagram illustrates: node [fontname = "helvetica"]; // Align gerrit repos and docs directories {rank=same doc aaf aai appc repoelipse vnfsdk vvp} - {rank=same releasenotestemplate localappcdocs } + {rank=same componentinfotemplate localappcdocs } //Show submodule linkage to docs directory submodules -> localappcdocs [style=dotted]; @@ -72,15 +76,15 @@ The following diagram illustrates: gerrit -> aaf; gerrit -> aai; gerrit -> appc; - gerrit -> repoelipse; repoelipse [label=". . . ."]; + gerrit -> repoelipse; repoelipse [label=". . . ."]; gerrit -> vnfsdk; gerrit -> vvp; - //Show example of local appc instance release notes - appc -> localappcdocs; localappcdocs [label="docs"]; - localappcdocs -> releasenotesinstance; releasenotesinstance [label="release-notes"]; - releasenotesinstance -> relnoteindexinstance; relnoteindexinstance [label="index.rst", shape=box]; - releasenotesinstance -> relnoteotherinstance; relnoteotherinstance [label="... other sections", shape=box]; + //Show example of local appc instance of component info + appc -> localappcdocs; localappcdocs [label="docs"]; + localappcdocs -> componentinfoinstance; componentinfoinstance [label="component-info"]; + componentinfoinstance -> compinfoindexinstance; compinfoindexinstance [label="index.rst", shape=box]; + componentinfoinstance -> compinofotherinstance; compinofotherinstance [label="... other sections", shape=box]; //Show detail structure of a portion of doc/docs _images _static _templates multiple master documents omitted doc -> docs; @@ -91,14 +95,15 @@ The following diagram illustrates: docs -> indexdirelipse; indexdirelipse [label="...other\ndocuments"]; docs -> submodules - //Example Release notes document + //Example Release document, section release notes, and reference to an instance of component-info release -> releasenotes; releasenotes [label="release-notes"]; releasenotes -> lowerlevelindex; lowerlevelindex [label="index.rst", shape=box]; + lowerlevelindex -> componentinfoinstance; - //Example release-notes template - rsttemplates -> releasenotestemplate; releasenotestemplate [label="release-notes"]; - releasenotestemplate -> relnoteindex; relnoteindex [label="index.rst", shape=box]; - releasenotestemplate -> relnoteother; relnoteother [label="... other sections", shape=box]; + //Example component-info template + rsttemplates -> componentinfotemplate; componentinfotemplate [label="component-info"]; + componentinfotemplate -> compinfotmpindex; compinfotmpindex [label="index.rst", shape=box]; + componentinfotemplate -> compinfotmpother; compinfotmpother [label="... other sections", shape=box]; } In the toctree @@ -106,7 +111,7 @@ In the toctree To include your project specific documentation in the composite documentation, first identify where your project documentation should be included. -Say your project provides release-notes and should be referenced in the `doc/docs/release/release-notes/index.rst toctree`, then: +Say your project provides component-info and should be referenced in the `doc/docs/release/release-info/index.rst toctree`, then: .. code-block:: bash @@ -123,10 +128,11 @@ it, example: .. toctree:: :maxdepth: 1 - ../../submodules/<your_repo>/docs/release-notes/index + ../../submodules/<your_repo>/docs/component-info/index When finished, you can request a commit to the doc project repository. -Be sure to add the project leader of the docs project as a reviewr of the change you just pushed in gerrit. +Be sure to add the PTL of the docs project as a reviewer of the change you just +pushed in gerrit. .. code-block:: bash diff --git a/docs/guide/onap-developer/how-to-use-docs/index.rst b/docs/guide/onap-developer/how-to-use-docs/index.rst index f2ec27587..6a393721d 100644 --- a/docs/guide/onap-developer/how-to-use-docs/index.rst +++ b/docs/guide/onap-developer/how-to-use-docs/index.rst @@ -4,7 +4,7 @@ Documentation ============= .. toctree:: - :maxdepth: 2 + :maxdepth: 3 documentation-guide include-documentation |