From ba873c46900a726bbc70680a04f5ae5611d7f392 Mon Sep 17 00:00:00 2001
From: Ron Stone <ronald.stone@windriver.com>
Date: Tue, 17 Dec 2024 14:46:13 +0000
Subject: [PATCH] Document doc strucure limitations

Docuement limitation to one 'master' index file at root of each document.

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

diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst
index d2e27821c..a2874509d 100644
--- a/doc/source/contributor/doc_contribute_guide.rst
+++ b/doc/source/contributor/doc_contribute_guide.rst
@@ -215,6 +215,78 @@ Spec documentation is found in the
 The ``specs/2019.03`` directory contains the documentation files for approved
 and implemented specs.
 
+------------------
+Document structure
+------------------
+   
+.. begin-document-structure
+   
+Each document consists of one Sphinx index file and some number of topic files.
+   
+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.
+   
+.. important::
+   
+   Additional indexes, either at the root of the document or in subfolders, are
+   not allowed.
+   
+   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
+   
+   
+   ------------------
+   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
+
 -------------
 Writing style
 -------------