Update How To Guide & Git submodules

vnfrqts/requirements master advanced beyond submodule reference in doc before verify job available
updated git reference to current level

Improvements in the how to guide describing submodule integration

Updated sphinx configuration to support sequence diagrams
Temporary exclusion filter reduced for seed documents with severe errors

Issue-Id: VNFRQTS-76
Change-Id: I3928a3d1e55a0731125e07186d8041b1614c3c8d
Signed-off-by: Rich Bennett <rb2745@att.com>

1 files changed, 128 insertions, 97 deletions

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 3471ac1ec..7b2818c6a 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
@@ -1,60 +1,116 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
-.. _include-documentation:
 
-============================
-Including your Documentation
-============================
-
-.. contents::
-   :depth: 3
-   :local:
+Setting Up
+==========
+Some initial steps are required to connect a project with
+the master document structure and enable automated publishing of
+changes as summarized in the following diagram and described detail 
+below.
+
+.. seqdiag::
+
+   seqdiag {
+     RD [label = "Read The Docs",                color =lightgreen ];
+     DA [label = "Doc Project\nAuthor/Committer",   color=lightblue];
+     DR [label = "Doc Gerrit Repo" ,                     color=pink];
+     PR [label = "Other Project\nGerrit Repo",          color=pink ];
+     PA [label = "Other Project\nAuthor/Committer", color=lightblue];
+     
+     === One time setup doc project only ===
+     RD  ->   DA [label = "Account Setup" ]; 
+     DA  ->   DR [label = "Create initial\nrepository content"];
+     DA  <<-- DR [label = "Merged" ];
+     RD  <--  DA [label = "Connect gerrit.onap.org" ];
+     === For each project & repository containing document source ===
+     DA  ->   PR [label = "Other Project Contribution to Setup\ndocs directory, index, other initial content" ];
+     PR  <--  PA [label = "Review/Merge Change" ];
+     DA  <--  PR [label = "Change Merged" ];     
+     DA  ->   DR [label = "Add Other Project Repo as\nGit submodule in doc project" ];
+     DA  <--  DR [label = "Change Merged" ];
+     }
+     
+     
+
+Setup doc project
+-----------------
+These steps are performed only once for the doc project and include:
 
-In your project repository
---------------------------
+(1) creating in the doc repository an initial:
+	- sphinx master document index
+	- directory structure aligned with the document structure
+	- set of test performed in jenkins verify jobs
+	- configuration for sphinx plugins and redendering of content
+  
+(2) establishing an account at readthedocs connected with gerrit.onap.org
 
-Add your documentation to your repository in the folder structure and
-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
+Setup other project(s)
+----------------------
+These steps are performed for each new project repo (referred to in the
+next three code blocks as $newreponame) the master document
+in doc repository references and include:
 
-   git clone ssh://<your_id>@gerrit.onap.org:29418/doc
-   cp -p doc/docs/templates/component-info <your_repo>/docs/component-info/
+(1) clone, modify, and commit to the other project an initial: docs top
+level directory; index.rst; any other intial content.   
 
+.. code-block:: bash
 
-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.
+   git clone ssh://<your_id>@gerrit.onap.org:29418/$newreponame
+   cd $newreponame
+   mkdir docs
+   echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
 
-.. _Developer Best Practices: https://wiki.onap.org/x/BZZk
+   $newreponame
+   ============
 
+   .. toctree::
+      :maxdepth: 1
+      
+   " >  docs/index.rst
+   
+   git add .
+   git commit -m "Add RST docs directory and index" -s
+   git commit --amend
+   # modify the commit message to comply with ONAP best practices
+   git review
+   
+When the above commit is reviewed and merged complete step 2 before any
+new changes are merged into $newreponame.
+	
+(2) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the other project and initialized as a git submodule.
+	
 .. code-block:: bash
 
+   git clone ssh://<your_id>@gerrit.onap.org:29418/doc
+   # For top level repositories use the following
+   mkdir doc/docs/submodules/$reponame
+   # For lower level repositories you may need to make a directory for each node in path
+   
+   echo "../submodules/$newreponame/index.rst" >> docs/release/index.rst
+   cd doc/docs/submodules/$reponame
+   
+   git submodule git https://gerrit.onap.org/r/$reponame
+   git submodule init $reponame/
+   git submodule update $reponame/
+   
+   
    git add .
-   git commit --signoff --all
+   git commit -m "Add $newreponame as asubmodule" -s
+   git commit --amend
+   # modify the commit message to comply with ONAP best practices
    git review
+   
 
-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`.
+The diagram below illustrates what is accomplished in the setup steps
+above from the perspective of a file structure created for local test,
+jenkins verify job, and/or merge/publish documentation including:
 
-The following diagram illustrates:
   - all ONAP gerrit project repositories,
-  - 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.
+  - the doc project repository including a master document index.rst, templates, configuration
+  - the submodules directory where other project repositories and directories/files may be referenced
+  - newreponame project repository being added and integrated.
 
 
 .. graphviz::
@@ -64,81 +120,54 @@ The following diagram illustrates:
    size="8,12";
    node [fontname = "helvetica"];
    // Align gerrit repos and docs directories
-   {rank=same doc aaf aai appc repoelipse vnfsdk vvp}
-   {rank=same componentinfotemplate localappcdocs }
+   {rank=same doc aaf aai newreponame repoelipse vnfsdk vvp}
+   {rank=same confpy release templates masterindex submodules otherdocdocumentelipse}
 
-   //Show submodule linkage to docs directory
-   submodules -> localappcdocs [style=dotted];
 
    //Illustrate Gerrit Repos and provide URL/Link for complete repo list
    gerrit [label="gerrit.onap.org/r", href="https://gerrit.onap.org/r/#/admin/projects/" ];
    gerrit -> doc;
    gerrit -> aaf;
    gerrit -> aai;
-   gerrit -> appc;
-   gerrit -> repoelipse;                                      repoelipse [label=". . . ."];
+   gerrit -> newreponame; 
+   gerrit -> repoelipse;
+             repoelipse [label=". . . ."];
    gerrit -> vnfsdk;
    gerrit -> vvp;
 
-   //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 example of local newreponame instance of component info
+   newreponame -> newreponamedocsdir;
+   newreponamesm -> newreponamedocsdir;  
+                    newreponamedocsdir [label="docs"];
+   newreponamedocsdir -> newrepodocsdirindex; 
+                         newrepodocsdirindex [label="index.rst", shape=box];
 
-   //Show detail structure of a portion of doc/docs _images _static _templates multiple master documents omitted
+   //Show detail structure of a portion of doc/docs 
    doc  -> docs;
-   docs -> confpy;                                             confpy [label="conf.py",shape=box];
-   docs -> toplevelindex;                               toplevelindex [label="index.rst", shape=box];
+   docs -> confpy;                   
+           confpy [label="conf.py",shape=box];
+   docs -> masterindex; 
+           masterindex [label="Master index.rst", shape=box];
    docs -> release;
-   docs -> rsttemplates;                                 rsttemplates [label="templates"];
-   docs -> indexdirelipse;                             indexdirelipse [label="...other\ndocuments"];
+   docs -> templates;                                
+   docs -> otherdocdocumentelipse;  
+           otherdocdocumentelipse [label="...other\ndocuments"];
    docs -> submodules
-
-   //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 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];
+   
+   masterindex -> releasedocumentindex [style=dashed, label="sphinx\ntoctree\nreference"];
+   
+   //Show submodule linkage to docs directory
+   submodules -> newreponamesm [style=dotted,label="git\nsubmodule\nreference"];  
+                 newreponamesm [label="newreponame"];
+
+   //Example Release document index that references component info provided in other project repo
+   release -> releasedocumentindex;   
+              releasedocumentindex [label="index.rst", shape=box];
+   releasedocumentindex -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
+ 
    }
 
-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 component-info and should be referenced in the `doc/docs/release/release-info/index.rst toctree`, then:
-
-.. code-block:: bash
-
-   git clone ssh://<your_id>@gerrit.onap.org:29418/doc
-   vim doc/docs/release/release-notes/index.rst
-
-This opens the text editor. Identify where you want to add your release notes.
-If your release notes are to be added to the toctree, simply include the path to
-it, example:
-
-
-.. code-block:: bash
-
-   .. toctree::
-      :maxdepth: 1
-
-      ../../submodules/<your_repo>/docs/component-info/index
-
-When finished, you can request a commit to the doc project repository.
-Be sure to add the PTL of the docs project as a reviewer of the change you just
-pushed in gerrit.
-
-.. code-block:: bash
-   
-   git add .
-   git commit --signoff --all
-   git review
+THE FOLLOWING SECTION NEEDS TO BE CONSOLIDATED / UPDATED
 
 
 As a Hyperlink
@@ -302,3 +331,5 @@ Clone the doc repository and add your submodule using the commands below and whe
   git submodule update $reponame/
   git add .
   git review
+
+