Enhancement and additions for webinar

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

diff --git a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
similarity index 76%
rename from docs/guide/onap-developer/how-to-use-docs/include-documentation.rst
rename to docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
index f41268f..789ad75 100644 (file)
--- a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst
@@ -55,7 +55,7 @@ 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.
+First let's set two variables that will be used in the subsequent steps.
 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
@@ -68,6 +68,12 @@ clone requests over ssh.
 
 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.
+The following sequence will do this over ssh.
+
+.. caution::
+
+   If your access network restricts ssh, you will need to use equivalent git commands and
+   HTTP Passwords as described `here <http://wiki.onap.org/x/X4AP>`_.
        
 .. code-block:: bash
 
@@ -84,9 +90,23 @@ submodule and at least one reference from the doc project to the documentation i
    git commit -s
    git review
    
+.. caution::
+   Wait for the above change to be merged before any merge to the
+   project repository that you have just added as a submodule.
+   If the project repository added as submodule changes before the doc project merge, git may not
+   automatically update the submodule reference on changes and/or the verify job will
+   fail in the step below.
 
 
 The last step is to create a docs directory in your repository with an index.rst file.
+The following sequence will complete the minimum required over ssh.  As you have time
+to convert or add new content you can update the index and add files under the docs folder.
+
+.. hint::
+   If you have additional content, you can include it by editing the
+   index.rst file and/or adding other files before the git commit.
+   See `Templates and Examples`_ below and :ref:`converting-to-rst` for more information.
+   
 
 .. code-block:: bash
 
@@ -110,10 +130,11 @@ The last step is to create a docs directory in your repository with an index.rst
 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:
-
-  - all ONAP gerrit project repositories,
-  - the doc project repository master document index.rst, templates, configuration
-  - the submodules directory where other project repositories and directories/files may be referenced
+  - 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::
@@ -177,10 +198,39 @@ a jenkins verify job, and/or published release documentation including:
 Creating Restructured Text
 ==========================
 
-TODO Add simple example and references here
+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
+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;/>`_.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   ../../../templates/**/index
+
+In addition to these simple templates and examples 
+there are many open source projects (e.g. Open Daylight, Open Stack)
+that are using Sphinx and Readthedocs where you may find examples to start with.
+Working with project teams we will continue to enhance templates here and
+capture frequently asked questions on the developer wiki question 
+topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_.
+
+Each project should: decide what is relevant content; determine the
+best way to create/maintain it in a CI/CD process; and work with the
+documentation team to reference content from the master index and guides.
+Consider options including filling in a template, 
+identifying existing content that can be used as is or
+easily converted, and use of Sphinx directives/extensions to automatically
+generate restructured text from other source you already have.
 
 Links and References
-====================
+--------------------
 It's pretty common to want to reference another location in the
 ONAP documentation and it's pretty easy to do with
 reStructuredText. This is a quick primer, more information is in the