Updates to How to Guide
Improve How to Use Documentation Guide including display
existing templates, consistency with the approved Jenkins
job templates, and other editorial improvements
Change-Id: I6a173a656acee2d675cb4af4c3070ab9ab9eb893
Issue-Id: DOC-59
Signed-off-by: Rich Bennett <rb2745@att.com>
diff --git a/docs/conf.py b/docs/conf.py
index 19b23f4..0ff5bd0 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -84,7 +84,7 @@
# directories to ignore when looking for source files.
exclude_patterns = [
'_build',
- 'templates'
+ 'submodules/vnfrqts'
]
# The reST default role (used for this markup: `text`) to use for all
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 ee0e5f2..f975417 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 @@
========
Index File
-==========
+----------
The index file must relatively reference your other rst files in that directory.
@@ -23,7 +23,7 @@
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 @@
Hello!
Writing RST Markdown
-====================
+--------------------
See http://sphinx-doc.org/rest.html .
@@ -59,22 +59,25 @@
.. 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 5dc3d71..380b05c 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 @@
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 @@
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 @@
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 @@
│ ├── develop
│ ├── document
│ └── test
- ├── administrator
+ ├── adminstrator
│ ├── configure
│ ├── deploy
│ └── operate
@@ -95,28 +88,29 @@
├── 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 8fa689f..3471ac1 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 @@
--------------------------
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 @@
--------------------------
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 @@
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 @@
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 @@
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 @@
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 @@
.. 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 f2ec275..6a39372 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 @@
=============
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
documentation-guide
include-documentation
diff --git a/docs/templates/component-info/index.rst b/docs/templates/component-info/index.rst
index e438da8..11fa2f2 100644
--- a/docs/templates/component-info/index.rst
+++ b/docs/templates/component-info/index.rst
@@ -1,8 +1,8 @@
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. http://creativecommons.org/licenses/by/4.0
-XXXX Component Information
-==========================
+Component Information Template
+==============================
High level architecture, design, and packaging information for release planning and delivery.
.. toctree::
diff --git a/docs/templates/index.rst b/docs/templates/index.rst
new file mode 100644
index 0000000..0f920a4
--- /dev/null
+++ b/docs/templates/index.rst
@@ -0,0 +1,14 @@
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _templates:
+
+Templates
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ **/index
+