summaryrefslogtreecommitdiffstats
path: root/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
diff options
context:
space:
mode:
authorRich Bennett <rb2745@att.com>2017-10-10 07:39:06 -0400
committerRich Bennett <rb2745@att.com>2017-10-10 07:44:50 -0400
commit7134cba7aa509a5ee7628244c52979e02807d252 (patch)
tree01d4f737b6c3b27515bd8f116850f838b7cc6830 /docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
parent2f3328219820a4be426981282350034b21e2e3f3 (diff)
Improve templates and add references in guides
See description of DOC-101 Added multipple conf.py files to test themes and multiple versions Created initial structure for references in developer architecture guide and release notes Change-Id: I7affcd1cb0258bef7cebe357a938080abe419693 Issue-ID: DOC-101 Signed-off-by: Rich Bennett <rb2745@att.com>
Diffstat (limited to 'docs/guides/onap-developer/how-to-use-docs/include-documentation.rst')
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/include-documentation.rst43
1 files changed, 36 insertions, 7 deletions
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 6d970123f..aa2def9d7 100644
--- a/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
@@ -202,19 +202,48 @@ Creating Restructured Text
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
-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:
- ../../../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)