Append .git submodule repositories, update guide

The submodule path hierarchy needs to support a name used as
hierarchy for lower level repositories or groupIDs AND allow
for a repository at each level eg submodules/appc and
submodules/appc/deployment are both repos. When viewed
in the submodule directory structure in the doc project, a
repository will have .git appended. The above example would
be submodules/appc.git submodules/appc/deployment.git

Change how to guide and convert existing submodule names
Rebased prior change

Change-Id: Ie16b8bbda7562aaaee3c21eb504dc6e293c98cbd
Issue-ID: DOC-33
Signed-off-by: Rich Bennett <rb2745@att.com>

9 files changed, 47 insertions, 41 deletions

diff --git a/.gitmodules b/.gitmodules
index 50be5f26b..146a3c897 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,25 +1,25 @@
 [submodule "docs/submodules/vnfrqts/guidelines"]
-	path = docs/submodules/vnfrqts/guidelines
+	path = docs/submodules/vnfrqts/guidelines.git
 	url = ../vnfrqts/guidelines
 	branch = .
 	ignore = dirty
 [submodule "docs/submodules/vnfrqts/requirements"]
-	path = docs/submodules/vnfrqts/requirements
+	path = docs/submodules/vnfrqts/requirements.git
 	url = ../vnfrqts/requirements
 	branch = .
 	ignore = dirty
 [submodule "docs/submodules/appc"]
-	path = docs/submodules/appc
+	path = docs/submodules/appc.git
 	url = ../appc
 	branch = .
 	ignore = dirty
 [submodule "docs/submodules/cli"]
-	path = docs/submodules/cli
+	path = docs/submodules/cli.git
 	url = ../cli
         branch = .
         ignore = dirty
 [submodule "docs/submodules/clamp"]
-	path = docs/submodules/clamp
+	path = docs/submodules/clamp.git
 	url = ../clamp
         branch = .
         ignore = dirty
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 9052090bd..f41268f99 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
@@ -24,10 +24,12 @@ below.
      DA  ->   DR [label = "Create initial\n doc repository content"];
      DA  <<-- DR [label = "Merge" ];
      RD  <--  DA [label = "Connect gerrit.onap.org" ];
-     === For each new project repository containing document source ===
-     DA  ->   DR [label = "Add new project repo as\ngit submodule" ];
-     DA  <--  DR [label = "Merge" ];     
-     PA  ->   PR [label = "Create in new project repo\ntop level directory and index.rst" ];
+     === For each project repository containing document source ===
+     PA  ->   DR [label = "Add project repo as\ngit submodule" ];
+     DR  ->   DA [label = "Review & Plan to\nIntegrate Content with\nTocTree Structure" ];
+     DR  <--  DA [label = "Vote +2/Merge" ];
+     PA  <--  DR [label = "Merge Notification" ];     
+     PA  ->   PR [label = "Create in project repo\ntop level directory and index.rst" ];
      PR  ->   DA [label = "Add as Reviewer" ];
      PR  <--  DA [label = "Approve and Integrate" ];
      PA  <--  PR [label = "Merge" ];
@@ -49,40 +51,46 @@ These steps are performed only once for the doc project and include:
 doc project repo in gerrit.onap.org.
 
 
-Setup new project repositories(s)
----------------------------------
-These steps are performed for each new project repo (referred to in the
-next two code blocks as $reponame):
+Setup project repositories(s)
+-----------------------------
+These steps are performed for each project repository that provides documentation. 
+
+First let's set two variables that will be used in the following examples.
+Set reponame to the project repository you are setting up just as it appears in the
+**Project Name** column of the Gerrit projects page.
+Set lfid to your Linux Foundation identity that you use to login to gerrit or for git
+clone requests over ssh.
 
-(1) clone, modify, and commit to the doc project: a directory under doc/docs/submodules with the same path/name as the new project initialized as a git submodule.
-	
 .. code-block:: bash
 
-   reponame=<your_repo_name>
+   reponame=
+   lfid=
+
+The next step is to add a directory in the doc project where your project will be included as a 
+submodule and at least one reference from the doc project to the documentation index in your repository.
+	
+.. code-block:: bash
 
-   git clone ssh://<your_id>@gerrit.onap.org:29418/doc
+   git clone ssh://$lfid@gerrit.onap.org:29418/doc
    cd doc
    mkdir -p `dirname docs/submodules/$reponame`
-   git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame
-   git submodule init docs/submodules/$reponame
-   git submodule update docs/submodules/$reponame
+   git submodule add https://gerrit.onap.org/r/$reponame docs/submodules/$reponame.git
+   git submodule init docs/submodules/$reponame.git
+   git submodule update docs/submodules/$reponame.git
 
-   echo "   $reponame <../submodules/$reponame/docs/index>" >> docs/release/repolist.rst
+   echo "   $reponame <../submodules/$reponame.git/docs/index>" >> docs/release/repolist.rst
    
    git add .
-   git commit -m "Add $reponame as a submodule" -s
-   git commit --amend
-   # modify the commit message to comply with ONAP best practices
+   git commit -s
    git review
    
 
 
-(2) clone, modify, and commit to the new project an initial: docs top
-level directory; index.rst; any other intial content.   
+The last step is to create a docs directory in your repository with an index.rst file.
 
 .. code-block:: bash
 
-   git clone ssh://<your_id>@gerrit.onap.org:29418/$reponame
+   git clone ssh://$lfid@gerrit.onap.org:29418/$reponame
    cd $reponame
    mkdir docs
    echo ".. This work is licensed under a Creative Commons Attribution 4.0 International License.
@@ -95,9 +103,7 @@ level directory; index.rst; any other intial content.
    " >  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 commit -s
    git review
    
 
@@ -137,8 +143,8 @@ a jenkins verify job, and/or published release documentation including:
    reponame -> reponamedocsdir;
    reponamesm -> reponamedocsdir;  
                     reponamedocsdir [label="docs"];
-   reponamedocsdir -> newrepodocsdirindex; 
-                         newrepodocsdirindex [label="index.rst", shape=box];
+   reponamedocsdir -> repnamedocsdirindex; 
+                         repnamedocsdirindex [label="index.rst", shape=box];
 
    //Show detail structure of a portion of doc/docs 
    doc  -> docs;
@@ -156,7 +162,7 @@ a jenkins verify job, and/or published release documentation including:
    
    //Show submodule linkage to docs directory
    submodules -> reponamesm [style=dotted,label="git\nsubmodule\nreference"];  
-                 reponamesm [label="reponame"];
+                 reponamesm [label="reponame.git"];
 
    //Example Release document index that references component info provided in other project repo
    release -> releasedocumentindex;   
@@ -164,7 +170,7 @@ a jenkins verify job, and/or published release documentation including:
    releasedocumentindex -> releaserepolist [style=dashed, label="sphinx\ntoctree\nreference"];
 			   releaserepolist  [label="repolist.rst", shape=box];
    release -> releaserepolist;
-   releaserepolist -> newrepodocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
+   releaserepolist -> repnamedocsdirindex [style=dashed, label="sphinx\ntoctree\nreference"];
  
    }
 
diff --git a/docs/guide/vnf-provider/index.rst b/docs/guide/vnf-provider/index.rst
index 342c35da9..c43c5f394 100644
--- a/docs/guide/vnf-provider/index.rst
+++ b/docs/guide/vnf-provider/index.rst
@@ -8,5 +8,5 @@ VNF Provider Guide
 .. toctree::
    :maxdepth: 2
 
-   ../../submodules/vnfrqts/guidelines/docs/index.rst
-   ../../submodules/vnfrqts/requirements/docs/index.rst
+   ../../submodules/vnfrqts/guidelines.git/docs/index.rst
+   ../../submodules/vnfrqts/requirements.git/docs/index.rst
diff --git a/docs/release/repolist.rst b/docs/release/repolist.rst
index f24ff43a4..1f57f7f93 100644
--- a/docs/release/repolist.rst
+++ b/docs/release/repolist.rst
@@ -5,8 +5,8 @@
    :maxdepth: 1
    :titlesonly:
    
-   appc <../submodules/appc/appc/docs/index>
-   vnfrqts/guidelines <../submodules/vnfrqts/guidelines/docs/index>
-   vnfrqts/requirements <../submodules/vnfrqts/requirements/docs/index>
-   cli <../submodules/cli/docs/index>
-   clamp <../submodules/clamp/docs/index>
+   appc <../submodules/appc.git/docs/index>
+   vnfrqts/guidelines <../submodules/vnfrqts/guidelines.git/docs/index>
+   vnfrqts/requirements <../submodules/vnfrqts/requirements.git/docs/index>
+   cli <../submodules/cli.git/docs/index>
+   clamp <../submodules/clamp.git/docs/index>
diff --git a/docs/submodules/appc b/docs/submodules/appc.git
-Subproject 3e0d86059e4926a0a5197f75f201284075811d9
+Subproject 3e0d86059e4926a0a5197f75f201284075811d9
diff --git a/docs/submodules/clamp b/docs/submodules/clamp.git
-Subproject 637af47ad9f91d5b91f742a1eea4041ee1b019c
+Subproject 637af47ad9f91d5b91f742a1eea4041ee1b019c
diff --git a/docs/submodules/cli b/docs/submodules/cli.git
-Subproject 8baba5cddb6dce7932872ec6e2709c28953c5c0
+Subproject 8baba5cddb6dce7932872ec6e2709c28953c5c0
diff --git a/docs/submodules/vnfrqts/guidelines b/docs/submodules/vnfrqts/guidelines.git
-Subproject d2592369b629974df1a00d9c7db730a1708dbe2
+Subproject d2592369b629974df1a00d9c7db730a1708dbe2
diff --git a/docs/submodules/vnfrqts/requirements b/docs/submodules/vnfrqts/requirements.git
-Subproject aae98f40234970b701d750f8975960c2a5d150c
+Subproject aae98f40234970b701d750f8975960c2a5d150c