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 789ad75..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
@@ -3,6 +3,7 @@
 
 Setting Up
 ==========
 
 Setting Up
 ==========

+

 Some initial set up is required to connect a project with
 the master document structure and enable automated publishing of
 changes as summarized in the following diagram and description below 
 Some initial set up is required to connect a project with
 the master document structure and enable automated publishing of
 changes as summarized in the following diagram and description below 


@@ -80,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
 


@@ -130,11 +131,12 @@ to convert or add new content you can update the index and add files under the d
 The diagram below illustrates what is accomplished in the setup steps
 above from the perspective of a file structure created for a local test,
 a jenkins verify job, and/or published release documentation including:
 The diagram below illustrates what is accomplished in the setup steps
 above from the perspective of a file structure created for a local test,
 a jenkins verify job, and/or published release documentation including:

-  - ONAP gerrit project repositories,
-  - doc project repository master document index.rst, templates, configuration, and other documents
-  - submodules directory where other project repositories and directories/files are referenced 
-  - file structure: directories (ellipses), files(boxes)
-  - references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges)
+
+- ONAP gerrit project repositories,
+- doc project repository master document index.rst, templates, configuration, and other documents
+- submodules directory where other project repositories and directories/files are referenced 
+- file structure: directories (ellipses), files(boxes)
+- references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges)

 
 
 .. graphviz::
 
 
 .. graphviz::


@@ -200,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)


@@ -340,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
 -----------------