Illustrate index dependency rules

Add diagrams to show correct and incorrect index relationships in a Kubernetes/Openstack doc.

Change-Id: I219cfad24f54d6ee4c7d4cafef36bd131693f7db
Signed-off-by: Ron Stone <ronald.stone@windriver.com>

doc/source/contributor/doc_contribute_guide.rst

@@ -218,7 +218,7 @@ and implemented specs.
 ------------------
 Document structure
 ------------------
-   
+
 .. begin-document-structure
 
 .. _index-rules:
@@ -226,10 +226,10 @@ Document structure
 ***********
 Index rules
 ***********
-   
+
 Each document consists of one main Sphinx index file, with two optional ones
 for each of Kubernetes and OpenStack content, if applicable.
-   
+
 The index file contains one or more *toctrees*, which define the manifest and
 structure of topics to be included in the document. The index file must be at
 the root of the document's folder structure. If your document contains a mix of
@@ -268,7 +268,7 @@ the two subindexes:
    =========
    OpenStack
    =========
-   
+
    .. toctree::
 
       openstack/index-1b466179efc3
@@ -280,62 +280,74 @@ random strings ``768a6e9aaeff`` and ``1b466179efc3`` were added by
 :command:`tox -e newfile` and will differ in your usage.)
 
 .. important::
-   
+
    Additional indexes, either at the root of the document or in subfolders, are
    not allowed.
-   
+
+   The following images provide examples of correct and incorrect layouts.
+
+   .. figure:: figures/index-structure-ok-2.png
+
+      **Correct Kubernetes/OpenStack layout**
+
+
+   .. figure:: figures/index-structure-wrong.png
+
+      **Incorrect Kubernetes/OpenStack layout**
+
+
    Use section headings in the index file to define document structure. For
    example:
-   
-.. code-block::
 
-   .. _contribute:
-   
-   ==================
-   Contributor Guides
-   ==================
-   
-   Welcome to the StarlingX community! We are glad you are here.
-   
-   If you are new to the project, take a moment to review the
-   `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_.
-   
-   ---------------------------
-   Contribute to documentation
-   ---------------------------
-   
-   .. toctree::
-      :maxdepth: 1
-   
-      doc_contribute_guide
-      api_contribute_guide
-      release_note_contribute_guide
-      blog_contribute_guide
-      website_contribute_guide
-   
+   .. code-block::
 
-   
-   ------------------
-   Contribute to code
-   ------------------
-   
-   StarlingX follows the `OpenStack developer contribution guidelines
-   <https://docs.openstack.org/infra/manual/developers.html>`_. Additional
-   StarlingX-specific resources are listed below.
-   
-   .. toctree::
-      :maxdepth: 1
-   
-      development_process
-      /developer_resources/code-submission-guide
-      /developer_resources/debug_issues
-   
-   --------------------
-   Additional resources
-   --------------------
-   
-   * `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_
-   * :doc:`/developer_resources/index`   
+      .. _contribute:
+
+      ==================
+      Contributor Guides
+      ==================
+
+      Welcome to the StarlingX community! We are glad you are here.
+
+      If you are new to the project, take a moment to review the
+      `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_.
+
+      ---------------------------
+      Contribute to documentation
+      ---------------------------
+
+      .. toctree::
+         :maxdepth: 1
+
+         doc_contribute_guide
+         api_contribute_guide
+         release_note_contribute_guide
+         blog_contribute_guide
+         website_contribute_guide
+
+
+
+      ------------------
+      Contribute to code
+      ------------------
+
+      StarlingX follows the `OpenStack developer contribution guidelines
+      <https://docs.openstack.org/infra/manual/developers.html>`_. Additional
+      StarlingX-specific resources are listed below.
+
+      .. toctree::
+         :maxdepth: 1
+
+         development_process
+         /developer_resources/code-submission-guide
+         /developer_resources/debug_issues
+
+      --------------------
+      Additional resources
+      --------------------
+
+      * `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_
+      * :doc:`/developer_resources/index`
 
 .. end-document-structure
 
@@ -1651,7 +1663,7 @@ When using external references, be sure to prefix the URL with either
    When providing an example of a URL format, treat the example as code by
    either placing it in a ``.. code-block::`` or in double backticks, for
    example:
-   
+
    .. code-block::
 
       ``https://<fqdn>/<path>``