From 47040fa69b65582032922cf1bed3cf3dfd69cef4 Mon Sep 17 00:00:00 2001
From: Ron Stone <ronald.stone@windriver.com>
Date: Mon, 23 Dec 2024 16:10:30 +0000
Subject: [PATCH] Index and folder rules

Add rules for creating index and folder layouts in documentation.

Change-Id: Ia1c235e505b03865f5ea0ba3de5bd60b8aa98d76
Signed-off-by: Ron Stone <ronald.stone@windriver.com>
---
 .../contributor/doc_contribute_guide.rst      | 85 +++++++++++++++++--
 1 file changed, 79 insertions(+), 6 deletions(-)

diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst
index a2874509d..81413cdc9 100644
--- a/doc/source/contributor/doc_contribute_guide.rst
+++ b/doc/source/contributor/doc_contribute_guide.rst
@@ -220,13 +220,65 @@ Document structure
 ------------------
    
 .. begin-document-structure
+
+.. _index-rules:
+
+***********
+Index rules
+***********
    
-Each document consists of one Sphinx index file and some number of topic files.
+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.
+the root of the document's folder structure. If your document contains a mix of
+Kubernetes and OpenStack topics, create a subdirectory for each with an index
+file for those topics and link it to the top-level index.
+
+For example:
+
+.. code-block:: bash
+
+   $ mkdir -p doc/source/newbook
+   $ cd doc/source/newbook
+   $ mkdir kubernetes
+   $ mkdir opemstack
+   $ tox -e newfile # follow instructions for creating a new index stub
+   $ cd kubernetes
+   $ tox -e newfile # create an index stub for kubernetes content
+   $ cd ../openstack
+   $ tox -e newfile # create an index stub for OpenStack content
+
+See :ref:`create-rst-files` for details on using :command:`tox -e newfile`
+
+In the book's main index under :file:`doc/source/newbook`, create entries to
+the two subindexes:
+
+.. code-block:: none
+
+   ==========
+   Kubernetes
+   ==========
+
+   .. toctree::
+
+      kubernetes/index-768a6e9aaeff
+
+   =========
+   OpenStack
+   =========
    
+   .. toctree::
+
+      openstack/index-1b466179efc3
+
+Add your Kubernetes and OpenStack content to the
+:file:`kubernetes/index-768a6e9aaeff.rst` and
+:file:`openstack/index-1b466179efc3.rst` files respectively. (Note that the
+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
@@ -261,6 +313,7 @@ the root of the document's folder structure.
       blog_contribute_guide
       website_contribute_guide
    
+
    
    ------------------
    Contribute to code
@@ -282,11 +335,30 @@ the root of the document's folder structure.
    --------------------
    
    * `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_
-   * :doc:`/developer_resources/index`
-   
+   * :doc:`/developer_resources/index`   
 
 .. end-document-structure
 
+****************
+Folder structure
+****************
+
+For any new document, create a new directory under :file:`source`. Create a
+subdirectory called :file:`figures` to hold images.
+
+* for short, simple documents, you can place index and topic files directly in
+  this new document directory.
+
+* for more complex documents with multiple chapters, create one subdirectory
+  for each chapter, for example, :file:`source/<book>/developer_resources`.
+
+* for documents that distinguish between Kubernetes and OpenStack, create one
+  subdirectory for each. Any chapter directory should be created under these.
+  For example: :file:`source/<book>/kubernetes/developer_resources`.
+
+  See the section on :ref:`index-rules` for more information.
+
+
 -------------
 Writing style
 -------------
@@ -295,8 +367,9 @@ Writing style
 
 StarlingX documentation follows many (but not all!) of the writing style
 guidelines described in the `OpenStack documentation writing style guide
-<https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_. Differences
-between the StarlingX and OpenStack practices are highlighted below.
+<https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_.
+Differences between the StarlingX and OpenStack practices are highlighted
+below.
 
 * Use Title Case for page titles. For example: