X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fguides%2Fonap-developer%2Fhow-to-use-docs%2Finclude-documentation.rst;fp=docs%2Fguide%2Fonap-developer%2Fhow-to-use-docs%2Finclude-documentation.rst;h=789ad7552c725daac7b5c0b45b3e122df28ead8f;hb=5baea4608e685f67e9dec77cfee57cacb73662dd;hp=f41268f999cfddcba8043aa2cf87f9d634dfdc49;hpb=a7f9e351a97b5b5b89e4e1eccd201a3e15e8f385;p=doc.git 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 f41268f99..789ad7552 100644 --- 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 `_. .. 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 `_. + +.. 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 `_. + +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