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. 
 
 -----------------------------
 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
 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 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
 
        
 .. 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
    
    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 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
 
 
 .. 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:
 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::
 
 
 .. graphviz::


@@ -177,10 +198,39 @@ a jenkins verify job, and/or published release documentation including:
 Creating Restructured Text
 ==========================
 
 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
 
 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
 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