Improve templates and add references in guides

[doc.git] / docs / guides / onap-developer / how-to-use-docs / include-documentation.rst

diff --git a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
index d6f720c..aa2def9 100644 (file)
--- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
@@ -81,7 +81,7 @@ The following sequence will do this over ssh.
    git clone ssh://$lfid@gerrit.onap.org:29418/doc
    cd doc
    mkdir -p `dirname docs/submodules/$reponame`
    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
+   git submodule add ../$reponame docs/submodules/$reponame.git

    git submodule init docs/submodules/$reponame.git
    git submodule update docs/submodules/$reponame.git
 
    git submodule init docs/submodules/$reponame.git
    git submodule update docs/submodules/$reponame.git
 


@@ -202,19 +202,48 @@ Creating Restructured Text
 
 Templates and Examples
 ----------------------
 
 Templates and Examples
 ----------------------

-Some templates are available that capture the kinds of information
-useful for different types of projects and provide simple examples of 
-restructured text.
-You can: browse the templates below; show source to look at the Restructured
-Text and Sphinx directives used; and then copy the source either from a browser window
+Templates are available that capture the kinds of information
+useful for different types of projects and provide some examples of 
+restructured text.  We organize templates in the following way to: help authors 
+understand relationships between documents; keep the user audience context in mind when writing; 
+and tailor sections for different kinds of projects.
+
+**Sections** Represent a certain type of content.   A section is **provided** in a repository, to
+to describe something about the characteristics, use, capability, etc. of things in that repository.
+A section may also be **referenced** from other sections and in other repositories.
+The notes in the beginning of each section template provide
+additional detail about what is typically covered and where there may be references to the section.
+
+**Collections** Are a set of sections that are typically provided for a particular type
+of project, repository, guide, reference manual, etc.
+
+You can: browse the template *collections* and *sections* below; show source to look at the Restructured
+Text and Sphinx directives used; copy the source either from a browser window

 or by downloading the file in raw form from
 or by downloading the file in raw form from

-the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_.
+the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_ and
+then add them to your repository docs folder and index.rst.
+
+
+Sections
+++++++++

 
 .. toctree::
    :maxdepth: 1
    :glob:
 
 
 .. toctree::
    :maxdepth: 1
    :glob:
 

-   ../../../templates/**/index
+   ../../../templates/sections/*
+
+
+Collections
++++++++++++
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   ../../../templates/collections/*
+
+

 
 In addition to these simple templates and examples 
 there are many open source projects (e.g. Open Daylight, Open Stack)
 
 In addition to these simple templates and examples 
 there are many open source projects (e.g. Open Daylight, Open Stack)


@@ -342,6 +371,7 @@ specified output folder directory.
 
 .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
 
 
 .. note:: Be sure to remove the `conf.py`, the static/ files and the output folder from the `<project>/docs/`. This is for testing only. Only commit the rst files and related content.
 

+.. _building-all-documentation:

 
 All Documentation
 -----------------
 
 All Documentation
 -----------------