diff options
author | 2017-09-06 08:07:22 -0400 | |
---|---|---|
committer | 2017-09-06 08:11:06 -0400 | |
commit | e4c42511f8b14d8935fd5de89e072ecd33215c8a (patch) | |
tree | 3e19bae887791ff2ce1946fc4275b51cdd886a4d | |
parent | 566885df28ad266eabb70af72b0155434385a64b (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>
-rw-r--r-- | .gitmodules | 10 | ||||
-rw-r--r-- | docs/guide/onap-developer/how-to-use-docs/include-documentation.rst | 64 | ||||
-rw-r--r-- | docs/guide/vnf-provider/index.rst | 4 | ||||
-rw-r--r-- | docs/release/repolist.rst | 10 | ||||
m--------- | docs/submodules/appc.git (renamed from docs/submodules/appc) | 0 | ||||
m--------- | docs/submodules/clamp.git (renamed from docs/submodules/clamp) | 0 | ||||
m--------- | docs/submodules/cli.git (renamed from docs/submodules/cli) | 0 | ||||
m--------- | docs/submodules/vnfrqts/guidelines.git (renamed from docs/submodules/vnfrqts/guidelines) | 0 | ||||
m--------- | docs/submodules/vnfrqts/requirements.git (renamed from docs/submodules/vnfrqts/requirements) | 0 |
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 |