summaryrefslogtreecommitdiffstats
path: root/docs/guide
diff options
context:
space:
mode:
authorRich Bennett <rb2745@att.com>2017-09-06 08:07:22 -0400
committerRich Bennett <rb2745@att.com>2017-09-06 08:11:06 -0400
commite4c42511f8b14d8935fd5de89e072ecd33215c8a (patch)
tree3e19bae887791ff2ce1946fc4275b51cdd886a4d /docs/guide
parent566885df28ad266eabb70af72b0155434385a64b (diff)
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>
Diffstat (limited to 'docs/guide')
-rw-r--r--docs/guide/onap-developer/how-to-use-docs/include-documentation.rst64
-rw-r--r--docs/guide/vnf-provider/index.rst4
2 files changed, 37 insertions, 31 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 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