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>
This commit is contained in:
Ron Stone 2024-12-23 16:10:30 +00:00
parent 129382a3ea
commit 47040fa69b

View File

@ -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: