Update and simplification of contribution guides

- Simplify docs contribution guide, using refs to OpenStack docs
- Minor formatting edits in other guides to make consistent
- Move doc to developer resources
- add link(s) to wiki from landing page

Patchset 2: Added ordered and enumerated lists, wording improvements per feedback.

Change-Id: I3b15a8127c0d742d726389e2b561424fca82567c
Signed-off-by: Kristal Dale <kristal.dale@intel.com>

doc/source/contributor/api_contribute_guide.rst

@@ -1,47 +1,52 @@
-=====================
+===================================
-API contributor guide
+API Documentation Contributor Guide
-=====================
+===================================
+
+OpenStack API working group has defined a guideline to follow for API
+documentation when a project provides a REST API service. API
+documentation information comes from RST source files stored in the
+project repository, that when built, generate HTML files.
+
+For additional information about the OpenStack guideline, refer to the
+`OpenStack API documentation guide <https://docs.openstack.org/doc-contrib-guide/api-guides.html>`_.
+
+.. contents::
+   :local:
+   :depth: 1
 
 ---------
 Locations
 ---------
 
-OpenStack API working group has defined a guideline to follow for API
+StarlingX API reference documentation exists in the following projects:
-documentation when a project provides a REST API service. API
-documentation information comes from RST source files stored in the
-project repository, that when built, generate HTML files. More details
-about the OpenStack API documentation can be found at:
-https://docs.openstack.org/doc-contrib-guide/api-guides.html.
 
-StarlingX API Reference documentation exists in the following projects:
+*  `starlingx/config`_: StarlingX System Configuration Management
+*  `starlingx/docs`_: StarlingX Documentation
 
--  `starlingx/config`_: StarlingX System Configuration Management
+   *  *stx-python-cinderclient* // only StarlingX-specific
--  `starlingx/docs`_: StarlingX Documentation
-
-   -  *stx-python-cinderclient* // only StarlingX-specific
       extensions to Cinder API are documented here
-   -  *stx-nova* // only StarlingX-specific extensions to Nova
+   *  *stx-nova* // only StarlingX-specific extensions to Nova
       API are documented here
-   -  *stx-glance* // only StarlingX-specific extensions to
+   *  *stx-glance* // only StarlingX-specific extensions to
       Glance API are documented here
-   -  *stx-neutron* // only StarlingX-specific extensions to
+   *  *stx-neutron* // only StarlingX-specific extensions to
       Neutron API are documented here
 
--  `starlingx/distcloud`_: StarlingX Distributed Cloud
+*  `starlingx/distcloud`_: StarlingX Distributed Cloud
--  `starlingx/fault`_: StarlingX Fault Management
+*  `starlingx/fault`_: StarlingX Fault Management
--  `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service
+*  `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service
    Management
--  `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware
+*  `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware
    Maintenance
--  `starlingx/nfv`_: StarlingX NFVI Orchestration
+*  `starlingx/nfv`_: StarlingX NFVI Orchestration
 
 --------------------
-Directory Structures
+Directory structures
 --------------------
 
-The directory structure of the API Reference documentation under each
+The directory structure of the API reference documentation under each
-StarlingX project repository is fixed. Here is an example showing
+StarlingX project repository is fixed. This example shows the `starlingx/config`_
-`starlingx/config`_ StarlingX System Configuration Management
+project:
 
 ::
 
@@ -51,36 +56,43 @@ StarlingX project repository is fixed. Here is an example showing
 	     ├── conf.py
 	     └── index.rst
 
-The initial modifications and additions to enable the API Documentation
+The initial modifications and additions to enable the API documentation
 service in each StarlingX project are as follows:
 
--  **.gitignore** modifications to ignore the building directories and
+``.gitignore``
-   HTML files for the API reference
+	Modifications to ignore the building directories and HTML files for the API
--  **.zuul.yaml** modifications to add the jobs to build and publish the
+	reference.
-   api-ref document
+
--  **api-ref/source** directory creation to store your API Reference
+``.zuul.yaml``
-   project directory
+	Modifications to add jobs to build and publish the ``api-ref`` document.
--  **api-ref/source/conf.py** configuration file to determine the HTML
+
-   theme, Sphinx extensions and project information
+``api-ref/source``
--  **api-ref/source/index.rst** source file to create your index RST
+	Directory created to store your API Reference project directory.
-   source file
+
--  **doc/requiremets.txt** modifications to add the os-api-ref Sphinx
+``api-ref/source/conf.py``
-   extension
+	Configuration file to set the HTML theme, Sphinx extensions, and project
--  **tox.ini** modifications to add the configuration to build the API
+	information.
-   reference locally
+
+``api-ref/source/index.rst``
+	Source file to create your index RST source file.
+
+``doc/requiremets.txt``
+	Modifications to add the ``os-api-ref`` Sphinx extension.
+
+``tox.ini``
+	Modifications to add the configuration to build the API reference locally.
 
 See `starlingx/config`_ [Doc] OpenStack API Reference Guide as an example of this
 first commit: https://review.opendev.org/#/c/603258/
 
-----------------------------
+--------------------------
-Creating the RST Source File
+Create the RST source file
-----------------------------
+--------------------------
 
-Once the API Documentation service has been enabled, you create the RST
+Once the API documentation service has been enabled, create the RST source files
-source files that document the API operations under the same API
+that document the API operations under the same API reference documentation
-Reference documentation project directory. The following shows the RST
+project directory. The following example shows the RST source file for the
-source file for the `starlingx/config`_ StarlingX System Configuration
+`starlingx/config`_ StarlingX System Configuration Management Configuration API v1:
-Management: Configuration API v1
 
 ::
 
@@ -88,18 +100,14 @@ Management: Configuration API v1
 	└── source
 		└── api-ref-sysinv-v1-config.rst
 
------------------------
+---------------------
-Creating the Index File
+Create the index file
------------------------
+---------------------
 
-After providing the RST source file as shown in the previous example,
+After providing the RST source file as shown in the previous example, add the
-you add the **index.rst** file. This file provides captioning, a brief
+``index.rst`` file. This file provides captioning, a brief description of the
-description of the document, and the table-of-contents structure with
+document, and the Table-of-Contents structure with depth restrictions. The
-depth restrictions. The **index.rst** file resides in the same folder as
+``index.rst`` file is located in the same folder as the RST source file:
-the RST source file.
-
-Here is an example using the `starlingx/config`_ StarlingX System
-Configuration Management: Configuration API v1:
 
 ::
 
@@ -108,8 +116,8 @@ Configuration Management: Configuration API v1:
 	    |___api-ref-sysinv-v1-config.rst
 	    |___index.rst
 
-The syntax of the **index.rst** file is fixed. Following shows the
+The syntax of the ``index.rst`` file is fixed. The following example shows the
-**index.rst** file used in the `starlingx/config`_:
+``index.rst`` file used in the `starlingx/config`_:
 
 ::
 
@@ -124,26 +132,30 @@ The syntax of the **index.rst** file is fixed. Following shows the
 	   api-ref-sys-v1-config
 
 
-Following are explanations for each of the four areas of the
+The ``index.rst`` file contains:
-**index.rst** file:
 
--  **Reference title:** Literal title that is used in the rendered
+``Reference title``
-   document. In this case it is "stx-config API Reference".
+	Literal title that is used in the rendered document. In this case it is
--  **Reference summary:** Literal summary of the rendered document. In
+	"stx-config API Reference".
-   this case it is "StarlingX System Configuration Management".
+
--  **Table-of-Contents tree structure and depth parameters:** The
+``Reference summary``
-   directive to create a TOC and to limit the depth of topics to "2".
+	Literal summary of the rendered document. In this case it is
--  **RST source file root name:** The source file to use as content. In
+	"StarlingX System Configuration Management".
-   this case, the file reference is "api-ref-sys-v1-config". This
+
-   references the **api-ref-sys-v1-config.rst** file in the same folder
+``Table-of-Contents tree structure and depth parameters``
-   as the **index.rst** file.
+	The directive to create a TOC and to limit the depth of topics to "2".
+
+``RST source file root name``
+	The source file to use as content. In this case, the file reference is
+	`api-ref-sys-v1-config`. This references the ``api-ref-sys-v1-config.rst``
+	file in the same folder as the ``index.rst`` file.
 
 ------------------
-REST METHOD Syntax
+REST method syntax
 ------------------
 
-Following is the syntax for each REST METHOD in the RST source file
+This section describes the syntax for each REST method in the RST source file
-(e.g. **api-ref-sys-v1-config.rst**).
+(for example ``api-ref-sys-v1-config.rst``).
 
 ::
 
@@ -225,18 +237,16 @@ Following is the syntax for each REST METHOD in the RST source file
 	    ]
 	}
 
-
+---------------------------------
-
+Build the reference documentation
-------------------------------------
+---------------------------------
-Building the Reference Documentation
-------------------------------------
 
 To build the API reference documentation locally in HTML format, use the
 following command:
 
 .. code:: sh
 
-   $ tox -e api-ref
+   tox -e api-ref
 
 The resulting directories and HTML files looks like:
 
@@ -253,86 +263,12 @@ The resulting directories and HTML files looks like:
 	     ...
 	    └── _static
 
+-----------------------------------------
+View the rendered reference documentation
+-----------------------------------------
 
---------------------------
+To view the rendered HTML API reference document in a browser, open up
-Closing Out a Bug or Story
+the ``index.html`` file.
---------------------------
-
-If you are modifying a document as a result of a defect or
-feature that is associated with a StoryBoard Story or Launchpad
-Bug, you must take steps to link your submission (Gerrit Review)
-to the story or bug.
-
-To link a story, add the following lines in your
-commit message.
-Be sure to use the actual story ID and task ID:
-
-* Story: $story_id
-* Task: $task_id
-
-Following is an example that links a Gerrit Review with Story
-2003375 and Task 2444:
-
-::
-
-   Change the tox.ini directory regarding tox.ini dependencies
-
-   Story: 2003375
-   Task: 24444
-
-**NOTE:** You must provide a blank line before the lines
-used to identify the story and the task.
-If you do not provide this line, your submission will not
-link to the Storyboard's story.
-
-To link a bug, add the approprite lines in your commit message.
-Be sure to provide the actual bug numbers:
-
-* Closes-Bug: $bug_id
-* Partial-Bug: $bug_id
-* Related-Bug: $bug_id
-
-If your fix requires multiple commits, use "Partial-Bug"
-for all the commits except the final one.
-For the final commit, use "Closes-Bug".
-
-Following is an example commit message that closes out bug
-1804024:
-
-::
-
-   AIO Hardware Requirements: Updated AIO HW requirements.
-
-   Added Small HW form factor information simplex/duplex
-   AIO hardware requirements.
-
-   Closes-Bug: #1804024
-
-When you associate a story or bug with a Gerrit review, Gerrit
-automatically updates the status of the story or bug once the
-commit is merged.
-Again, be sure to provide a blank line just before the line
-identifying the bug.
-
-You can find more information on the StarlingX code submission
-guidelines on the
-`wiki <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
-
-To see the list of defects against StarlingX, see the
-`Launchpad Application <https://bugs.launchpad.net/starlingx>`_.
-
---------------------------------------------
-Viewing the Rendered Reference Documentation
---------------------------------------------
-
-To view the rendered HTML API Reference document in a browser, open up
-the **index.html** file.
-
-**NOTE:** The PDF build uses a different tox environment and is
-currently not supported for StarlingX.
-
-
-
 
 .. _starlingx/config: https://opendev.org/starlingx/config
 .. _starlingx/docs: https://opendev.org/starlingx/docs

doc/source/contributor/development_process.rst

@@ -2,9 +2,11 @@
 StarlingX Development Process
 =============================
 
+This section describes the StarlingX development process.
+
 .. contents::
    :local:
-   :depth: 2
+   :depth: 1
 
 ------------
 Introduction

doc/source/contributor/doc_contribute_guide.rst

@@ -1,288 +1,433 @@
 ===============================
-Documentation contributor guide
+Documentation Contributor Guide
 ===============================
 
-This guide provides information that allows you to contribute to the
+This section describes the guidelines for contributing to the StarlingX
-`StarlingX documentation <https://docs.starlingx.io/>`_.
+documentation.
 
-Information common to OpenStack workflow, writing styles, and conventions
+.. contents::
-is not included in this guide. Instead refer to the
+   :local:
+   :depth: 1
+
+------------------
+General guidelines
+------------------
+
+The StarlingX documentation uses reStructuredText (RST) markup syntax with
+Sphinx extensions. Most writing and markup conventions are based on the
 `OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
 
----------
+When writing documentation, follow the StarlingX documentation guidelines:
-Locations
----------
 
-StarlingX documentation consists of several types of manuals and is found
+* `Writing style`_
-in the `starlingx/docs`_ and `starlingx/specs`_ repositories.
+* `RST conventions`_
 
-You can clone these repositories by:
+Verify that your changes render properly by `building the documentation locally <https://docs.openstack.org/doc-contrib-guide/docs-builds.html>`_.
+
+******************
+Contribute content
+******************
+
+If you are looking for work to complete, review these reports:
+
+* Refer to the `StarlingX documentation StoryBoard <https://storyboard.openstack.org/#!/project/starlingx/docs>`_ for topics that need content. Many topics have stub pages in the documentation with a link to the associated story.
+
+* Find open `documentation bugs on Launchpad <https://bugs.launchpad.net/starlingx/+bugs?field.tag=stx.docs>`_.
+
+
+When creating a Gerrit review, link the associated story, task, or bug in the
+comment, according to `Starlingx Code Submission Guidelines <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
+
+For example, link a story and task in a comment:
 
 ::
 
-   $ git clone https://opendev.org/starlingx/docs.git
+  Brief description of change.
-   $ git clone https://opendev.org/starlingx/specs.git
 
-These projects contain hierarchy that organizes the documentation by topic:
+  Detailed description of change.
 
-Installation Guide
+  Story: $story_id
-    Describes how to install StarlingX onto Bare Metal or into a virtual
+  Task: $task_id
-    environment.
 
-Developer Guide
+Or, to link to the bug that the review fixes:
-    Describes how to build a StarlingX ISO image from the "master" branch.
 
-Project Specifications
+::
-    Describes specifications, specification templates, and processes for
-    submitting a specification.
 
-REST API Reference
+  Brief description of bug fix.
-    Describes StarlingX APIs.
 
-Release Notes
+  Detailed description of bug fix.
-    Provides release-specific information.
 
-Contribute
+  Closes-Bug: $bug_id
-    Provides guides on how to contribute to StarlingX API documentation,
-    release notes, and general documentation.
 
---------------------
+-----------------
-Directory Structures
+Docs organization
---------------------
+-----------------
 
-Directory structures vary depending on the type of documentation involved.
+Documentation for StarlingX is organized into the following sections:
-Think of the structure as one or more RST files per book.
 
-* A simple book consists of a single **index.rst** file.
+:doc:`/introduction/index`
-* A more complicated book could consist of an **index.rst** file as the book's
+  Overview of the StarlingX project.
-  landing page and a set of additional RST files for major sections of the book.
 
-The structure for the API Reference documentation deserves some extra explanation.
+:doc:`/deploy_install_guides/index`
-Most RST files for the API Reference content reside in top-level
+  Release-specific installation and deployment guides.
-StarlingX repositories, for example `starlingx/metal`_ or `starlingx/config`_.
-However, four API Reference RST files reside in `starlingx/docs`_,
-in **/api-ref/source**:
 
-* "Block Storage"
+:doc:`/configuration/index`
-* "Compute"
+  Configuration references for post-installation StarlingX system configuration.
-* "Image"
-* "Network".
 
-While there is a **/api-ref/source/index.rst** file along
+:doc:`/operations/index`
-side these other four RST files, it exists only because the Sphinx process
+  System administration and maintenance guides.
-needs that index file to build out the final web documentation tree.
-The actual landing page (content) for the API Reference documents
-is in the **/doc/source/api-ref/index.rst** file.
 
-In the `starlingx/specs`_ project, the **/doc/source/index.rst**
+:doc:`/api-ref/index`
-file is the main landing page for the StarlingX specifications page
+  REST API references for the StarlingX project. For additional information about
-(<https://docs.starlingx.io/specs/index.html>`_).
+  where REST API documentation is located, see `API documentation`_.
 
-The **/specs/2019.03** area contains the RST files for approved and
+:doc:`/cli_ref/index`
+  Reference for the StarlingX project command line interface (CLI).
+
+:doc:`/developer_resources/index`
+  Resources for developers using or building StarlingX.
+
+:doc:`/releasenotes/index`
+  Release notes for all StarlingX releases.
+
+:doc:`/contributor/index`
+  Overview and guidelines for contributing to StarlingX documentation.
+
+*****************
+API documentation
+*****************
+
+The structure and location of the REST API documentation deserves extra explanation.
+
+Most REST API content is generated from the StarlingX project associated with the
+API. For example, the documentation for the StarlingX metal REST API is
+generated from the `metal repository <https://opendev.org/starlingx/metal>`_.
+
+API references for StarlingX extensions are part of the docs repository, located
+in the ``api-ref`` project:
+
+* StarlingX extensions to the OpenStack Block Storage API
+* StarlingX extensions to the OpenStack Compute API
+* StarlingX extensions to the OpenStack Image API
+* StarlingX extensions to the OpenStack Networking API
+
+The ``api-ref`` project also contains index pages used by Sphinx to
+generate the final content tree. Note that the REST API landing page used to
+render content in the generated website is found in the ``doc`` project.
+
+For additional information on the API documentation, refer to :doc:`api_contribute_guide`.
+
+******************
+Spec documentation
+******************
+
+Spec documentation is found in the
+`Starlingx specs project <https://opendev.org/starlingx/specs>`_.
+
+The ``specs/2019.03`` directory contains the documentation files for approved and
 implemented specs.
 
------------------
+-------------
-Updating a Manual
+Writing style
------------------
+-------------
 
-If you need to update an existing manual, you need to find the appropriate RST
+StarlingX documentation follows many (but not all!) of the writing style
-source file, make your modifications, test them (i.e. build the manual), and
+guidelines described in the `OpenStack documentation writing style guide <https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_. Differences
-then submit the changes to Gerrit for approval.
+between the StarlingX and OpenStack practices are highlighted below.
 
------------------
+* Use Title Case for page titles. For example:
-Creating a Manual
------------------
 
-Creating a new manual involves at minimum providing a new **index.rst** file.
+  ::
-If the manual is more complex with additional content outside of the
-**index.rst** file, you need to provide additional RST files as well.
 
-As an example, consider a new manual that resides in **/doc/source/my-guide**.
+    ===============================
-Furthermore, suppose this manual's **index.rst** file contained two
+    Documentation Contributor Guide
-links to additional complicated topics: "Topic 1" and
+    ===============================
-"Topic 2".
 
-The content for the new manual exists in three files:
+* Start section titles with an action verb, but not a gerund (word that ends with -ing). For example:
 
-* **/doc/source/my-guide/index.rst**
+  ::
-* **/doc/source/my-guide/topic_1.rst**
-* **/doc/source/my-guide/topic_2.rst**
 
-Following shows the hierarchy:
+    ------------------
+    Configure endpoint
+    ------------------
+
+---------------
+RST conventions
+---------------
+
+StarlingX documentation follows many (but not all!) of the RST conventions
+described in the `OpenStack documentation RST conventions guide <https://docs.openstack.org/doc-contrib-guide/rst-conv.html>`_. If RST markup is
+not listed in this section's quick reference, refer to the OpenStack guide.
+
+For detailed information about RST and Sphinx extensions, refer to the following
+documents:
+
+* `Sphinx documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+* `reStructuredText primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+
+-------------------
+RST quick reference
+-------------------
+
+.. contents::
+   :local:
+   :depth: 1
+
+********
+Acronyms
+********
+
+Define acronym at first instance on page. After definition, use acronym only.
+
+**Input:**
 
 ::
 
-    ├── doc
+  :abbr:`CPU (Central Processing Unit)`
-    │   └── source
-    │       ├── my_guide
-    │       │   ├── index.rst
-    │       │   ├── topic_1.rst
-    │       │   ├── topic_2.rst
 
+**Output:**
 
------------------------
+:abbr:`CPU (Central Processing Unit)`
-Creating the Index File
------------------------
 
-The **index.rst** file provides captioning, a brief
+************
-description of the document, and the table-of-contents (TOC) structure
+Code samples
-with instructions on how to display or hide sub-topics.
+************
 
-The syntax of the **index.rst** file is fixed. Following shows the
+Format code snippets as standalone literal blocks.
-sample **index.rst** file for the new guide:
+
+**Input:**
 
 ::
 
-     ========
+  ::
-     My Guide
-     ========
 
-     The new guide.
+    ping 8.8.8.8
 
-     - :ref:`Topic 1 <topic_1>`
+**Output:**
-     - :ref:`Topic 2 <topic_2>`
-
-     .. toctree::
-        :hidden:
-
-        topic_1
-        topic_2
-
-Following are explanations for each of the four areas of the
-**index.rst** file:
-
--  **Reference title:** Literal title that is used in the rendered
-   document.
-   In this case it is "My Guide".
--  **Reference summary:** Literal summary of the rendered document.
-   In this case it is "The new guide."
--  **Table-of-Contents tree structure and sub-topic parameters:** The
-   directive to create a TOC and to specify the embedded topic links
-   should remain hidden.
-   If you want sub-topics to be part of the TOC, use the
-   ":maxdepth: x" directive where "x" is the depth you desire for
-   sub-topics in the TOC.
--  **RST source file root name:** The source files to use as content.
-   In this case, the file references are "topic_1" and "topic_2".
-   These reference the **topic_1.rst** and **topic_2.rst** files
-   in the same folder as the **index.rst** file.
-
-----------------------------------------------------
-Integrating the New Guide Into the Documentation Set
-----------------------------------------------------
-
-The previous section described how you can provide the files
-you need to create a new guide.
-This section describes how to add your new guide to the table of contents in the 
-documentation site.
-
-The **/doc/source/index.rst** file contains the structure
-that defines the StarlingX Documentation landing page.
-Inside the file, is a "Sections" area that lists the documents
-that appear in the table of contents.
-Add your new guide to the toctree definition in the index.rst file.
-
---------------------------
-Closing Out a Bug or Story
---------------------------
-
-If you are modifying a document as a result of a defect or
-feature that is associated with a StoryBoard Story or Launchpad
-Bug, you must take steps to link your submission (Gerrit Review)
-to the story or bug.
-
-To link a story, add the following lines in your
-commit message.
-Be sure to use the actual story ID and task ID with the commit:
-
-* Story: $story_id
-* Task: $task_id
-
-Following is an example that links a Gerrit Review with Story
-2003375 and Task 2444:
 
 ::
 
-   Change the tox.ini directory regarding tox.ini dependencies
+    ping 8.8.8.8
 
-   Story: 2003375
+********
-   Task: 24444
+Commands
+********
 
-**NOTE:** You must provide a blank line before the lines
+Format commands using the Sphinx ``command`` role.
-used to identify the Story and the Task.
-Furthermore, you must place these lines as the last lines
-in your commit message.
-If you do not follow these guidelines, your submission will not
-link to the Storyboard's story.
 
-To link a bug, add the appropriate lines in your commit message.
+**Input:**
-Be sure to provide the actual bug numbers:
-
-* Closes-Bug: $bug_id
-* Partial-Bug: $bug_id
-* Related-Bug: $bug_id
-
-If your fix requires multiple commits, use "Partial-Bug"
-for all the commits except the final one.
-For the final commit, use "Closes-Bug".
-
-Following is an example commit message that closes out bug
-1804024:
 
 ::
 
-   AIO Hardware Requirements: Updated AIO HW requirements.
+  :command:`system help`
 
-   Added Small HW form factor information simplex/duplex
+**Output:**
-   AIO hardware requirements.
 
-   Closes-Bug: #1804024
+Use the :command:`system help` command for the full list of options.
 
-When you associate a story or bug with a Gerrit review, Gerrit
+****************
-automatically updates the status of the story or bug once the
+Cross-references
-commit is merged.
+****************
-Again, be sure to provide a blank line just before the line
-identifying the bug.
 
-You can find more information on the StarlingX code submission
+Cross-reference to arbitrary locations in a document using the ``ref`` role and a
-guidelines on the
+named target. Named targets must precede a section heading. For more information
-`wiki <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
+on references, see
+`Internal Hyperlink Targets <http://docutils.sourceforge.net/docs/user/rst/quickref.html#internal-hyperlink-targets>`_
 
-To see the list of defects against StarlingX, see the
+**Input:**
-`Launchpad Application <https://bugs.launchpad.net/starlingx>`_.
-
---------------------------
-Building the Documentation
---------------------------
-
-To build the documentation locally in HTML format, use the
-following command:
-
-.. code:: sh
-
-   $ tox -e docs
-
-The resulting HTML files will be located in the **/doc/build**
-directory:
 
 ::
 
-     starlingx/docs/doc/
+  .. _my_named_target:
-     ├── build
-     │   └── html
 
-----------------------------------
+  ~~~~~~~~~~
-Viewing the Rendered Documentation
+  My section
-----------------------------------
+  ~~~~~~~~~~
 
-To view the rendered documentation in a browser, open up
+  This is the section we want to reference.
-the **index.html** file in your browser.
 
-**NOTE:** The PDF build uses a different tox environment and is
+  ...
-currently not supported for StarlingX.
+
+  This is the reference to :ref:`my_named_target`.
+
+**Output:**
+
+.. _my_named_target:
+
+~~~~~~~~~~
+My section
+~~~~~~~~~~
+
+This is the section we want to reference.
+
+...
+
+This is the reference to :ref:`my_named_target`.
+
+******************
+Information blocks
+******************
+
+Emphasize information using notices (an 'admonition' in Sphinx). Different types of notices exist to emphasize degrees of information importance.
+
+**Input:**
+
+::
+
+  .. note::
+
+     Use a ``note`` for a generic message.
+
+  .. seealso::
+
+     Use ``seealso`` for extra but helpful information.
+
+  .. important::
+
+     Use ``important`` for details that can be easily missed, but should not be
+     ignored by a user and are valuable before proceeding.
+
+  .. warning::
+
+     Use ``warning`` to call out information the user must understand
+     to avoid negative consequences.
+
+**Output:**
+
+.. note::
+
+   Use a ``note`` for a generic message.
+
+.. seealso::
+
+   Use ``seealso`` for extra but helpful information.
+
+.. important::
+
+   Use ``important`` for details that can be easily missed, but should not be
+   ignored by a user and are valuable before proceeding.
+
+.. warning::
+
+   Use ``warning`` to call out information the user must understand
+   to avoid negative consequences.
 
 
-.. _starlingx/docs: https://opendev.org/starlingx/docs
+***************
-.. _starlingx/specs: https://opendev.org/starlingx/specs
+Inline elements
-.. _starlingx/metal: https://opendev.org/starlingx/metal
+***************
-.. _starlingx/config: https://opendev.org/starlingx/config
+
+Format most inline elements such as filenames and paths, code fragments, parameters, or
+options with double back ticks.
+
+**Input:**
+::
+
+  ``/path/to/file.name``
+  ``--option``
+
+**Output:**
+
+Open the ``/path/to/file.name`` file.
+
+Optionally pass the ``--option`` with the command.
+
+Refer to the
+`OpenStack Inline elements guide <https://docs.openstack.org/doc-contrib-guide/rst-conv/inline-markups.html>`_
+for markup for other inline elements.
+
+*****
+Lists
+*****
+
+Use a bulleted list for a sequence of items whose order does not matter, such as a list of features.
+
+**Input:**
+
+::
+
+  * Banana
+  * Apple
+  * Orange
+
+**Output:**
+
+* Banana
+* Apple
+* Orange
+
+Use an enumerated list for a sequence of items whose order matters, such as in an ordered sequence of installation steps.
+
+**Input:**
+
+::
+
+  #. Wash apple.
+  #. Peel apple.
+  #. Eat apple.
+
+**Output:**
+
+#. Wash apple.
+#. Peel apple.
+#. Eat apple.
+
+Use a definition list for an unordered list where each item has a short definition, such as term/definition pairs.
+
+**Input:**
+
+::
+
+  Command A
+    Description of command A.
+
+  Command B
+    Description of command B.
+
+**Output:**
+
+Command A
+  Description of command A.
+
+Command B
+  Description of command B.
+
+****************
+Section headings
+****************
+
+Use up to three levels of headings in one file using the following characters:
+
+* Heading 1 (Page Title in Title Case) - underline and overline with equal signs;
+
+  * Heading 2 (Major page sections in Sentence case) - underline and overline with dashes;
+
+    * Heading 3 (subsections in Sentence case) - underline and overline with asterisks.
+
+Example RST:
+
+.. code-block:: rest
+
+   ==============
+   Document Title
+   ==============
+
+   Introduce the topic using 1-2 concise sentences. It should tell the user what
+   info can be found on this page.
+
+   .. contents::  // Use a local TOC to aid user navigation in the page
+      :local:
+      :depth: 1
+
+   ---------------
+   Section heading
+   ---------------
+
+   Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+   ******************
+   Subsection heading
+   ******************
+
+   Integer sed tortor nisi. Vivamus feugiat, urna in posuere gravida, ligula nunc hendrerit magna, nec tristique ex tortor non lorem.
+

doc/source/contributor/index.rst

@@ -1,16 +1,13 @@
 .. _contribute:
 
-==========
+==================
-Contribute
+Contributor Guides
-==========
+==================
 
-The following guides provide detailed instructions on the contribution workflow
+Welcome to the StarlingX community! We are glad you are here.
-and conventions to be considered when contributing to the StarlingX documentation.
 
-StarlingX utilizes tooling and CI/CD environments from the OpenStack
+If you are new to the project, take a moment to review the
-Foundation. The source is hosted on `OpenDev's Git server`_.
+`StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_.
-
-.. _`OpenDev's Git server`: https://opendev.org/starlingx
 
 ---------------------------
 Contribute to documentation
@@ -19,43 +16,26 @@ Contribute to documentation
 .. toctree::
    :maxdepth: 1
 
+   doc_contribute_guide
    api_contribute_guide
    release_note_contribute_guide
-   doc_contribute_guide
 
--------------------
+------------------
-Development process
+Contribute to code
--------------------
+------------------
 
-For information on the StarlingX development process, refer to the following guide:
+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
-
+   Code Submission Guidelines <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>
----------------
-Build StarlingX
----------------
-
-Refer to the StarlingX Build Guide for instructions on how to build a StarlingX
-ISO image.
-
-.. toctree::
-   :maxdepth: 1
-
-   build_guide
 
 --------------------
 Additional resources
 --------------------
 
-Additional information about contributing to OpenStack documentation can be found
+* `StarlingX wiki <https://wiki.openstack.org/wiki/StarlingX>`_
-in the following guides:
+* :doc:`/developer_resources/index`
-
-* `OpenStack API documentation guide`_
-* `OpenStack Documentation Contributor Guide`_
-
-.. _`OpenStack Documentation Contributor Guide`: https://docs.openstack.org/doc-contrib-guide/index.html
-
-.. _`OpenStack API documentation guide`: https://docs.openstack.org/doc-contrib-guide/api-guides.html

doc/source/contributor/release_note_contribute_guide.rst

@@ -1,41 +1,44 @@
 ===============================
-Release notes contributor guide
+Release Notes Contributor Guide
 ===============================
 
 Release notes for StarlingX projects are managed using Reno allowing release
 notes go through the same review process used for managing code changes.
 Release documentation information comes from YAML source files stored in the
-project repository, that when built in conjuction with RST source files,
+project repository, that when built in conjunction with RST source files,
 generate HTML files. More details about the Reno Release Notes Manager can
 be found at: https://docs.openstack.org/reno
 
+.. contents::
+   :local:
+   :depth: 1
+
 ---------
 Locations
 ---------
 
 StarlingX release notes documentation exists in the following projects:
 
--  `starlingx/clients`_: StarlingX Client Libraries
+*  `starlingx/clients`_: StarlingX Client Libraries
--  `starlingx/config`_: StarlingX System Configuration Management
+*  `starlingx/config`_: StarlingX System Configuration Management
--  `starlingx/distcloud`_: StarlingX Distributed Cloud
+*  `starlingx/distcloud`_: StarlingX Distributed Cloud
--  `starlingx/distcloud-client`_: StarlingX Distributed Cloud Client
+*  `starlingx/distcloud-client`_: StarlingX Distributed Cloud Client
--  `starlingx/fault`_: StarlingX Fault Management
+*  `starlingx/fault`_: StarlingX Fault Management
--  `starlingx/gui`_:  StarlingX Horizon plugins for new StarlingX services
+*  `starlingx/gui`_:  StarlingX Horizon plugins for new StarlingX services
--  `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service Management
+*  `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service Management
--  `starlingx/integ`_: StarlingX Integration and Packaging
+*  `starlingx/integ`_: StarlingX Integration and Packaging
--  `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware Maintenance
+*  `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware Maintenance
--  `starlingx/nfv`_: StarlingX NFVI Orchestration
+*  `starlingx/nfv`_: StarlingX NFVI Orchestration
--  `starlingx/tools`_: StarlingX Build Tools
+*  `starlingx/tools`_: StarlingX Build Tools
--  `starlingx/update`_: StarlingX Installation/Update/Patching/Backup/Restore
+*  `starlingx/update`_: StarlingX Installation/Update/Patching/Backup/Restore
--  `starlingx/upstream`_: StarlingX Upstream Packaging
+*  `starlingx/upstream`_: StarlingX Upstream Packaging
 
 --------------------
-Directory Structures
+Directory structures
 --------------------
 
 The directory structure of release documentation under each StarlingX project
-repository is fixed.  Here is an example showing **stx-confi** StarlingX System
+repository is fixed.  This example shows the ``stx-confi`` project:
-Configuration Management:
 
 ::
 
@@ -51,23 +54,35 @@ Configuration Management:
 The initial modifications and additions to enable the API Documentation service
 in each StarlingX project are as follows:
 
--  **.gitignore** modifications to ignore the building directories and HTML files
+``.gitignore``
-   for the Release Notes
+	Modifications to ignore the building directories and HTML files for the
--  **.zuul.yaml** modifications to add the jobs to build and publish the api-ref
+	release notes.
-   document
+
--  **releasenotes/notes/** directory creation to store your release notes files
+``.zuul.yaml``
-   in YAML format
+	Modifications to add jobs to build and publish the ``api-ref`` document.
--  **releasenotes/source** directory creation to store your API Reference project
+
-   directory
+``releasenotes/notes``
--  **releasenotes/source/conf.py** configuration file to determine the HTML theme,
+	Directory created to store your release notes files in YAML format.
-   Sphinx extensions and project information
+
--  **releasenotes/source/index.rst** source file to create your index RST source
+``releasenotes/source``
-   file
+	Directory created to store your API reference project directory.
--  **releasenotes/source/unrelased.rst** source file to avoid breaking  the real
+
-   release notes build job on the master branch
+``releasenotes/source/conf.py``
--  **doc/requiremets.txt** modifications to add the os-api-ref Sphinx extension
+	Configuration file to determine the HTML theme, Sphinx extensions, and
--  **tox.ini** modifications to add the configuration to build the API reference
+	project information.
-   locally
+
+``releasenotes/source/index.rst``
+	Source file to create your index RST source file.
+
+``releasenotes/source/unrelased.rst``
+	Source file to avoid breaking the real release notes build job on the master
+	branch.
+
+``doc/requiremets.txt``
+	Modifications to add the ``os-api-ref`` Sphinx extension.
+
+``tox.ini``
+	Modifications to add the configuration to build the API reference locally.
 
 See stx-config [Doc] Release Notes Management as an example of this first commit:
 https://review.opendev.org/#/c/603257/
@@ -76,11 +91,11 @@ Once the Release Notes Documentation service has been enabled, you can create a
 release notes.
 
 -------------------
-Release Notes Files
+Release notes files
 -------------------
 
-The following shows the YAML source file for the stx-config StarlingX System
+The following shows the YAML source file for the stx-config project:
-Configuration Management:
+
 `Release Summary R1.0 <http://git.openstack.org/cgit/openstack/stx-config/tree/releasenotes/notes/release-summary-6738ff2f310f9b57.yaml>`_
 
 ::
@@ -89,12 +104,12 @@ Configuration Management:
 	├── notes
 	│   └── release-summary-6738ff2f310f9b57.yaml
 
-
+To create a new release note that documents your code changes via the
-To create a new release note that document your code changes via tox newnote environment:
+tox newnote environment:
 
 $ tox -e newnote hello-my-change
 
-A YAML source file is created with a unique name under releasenote/notes/ directory:
+A YAML source file is created with a unique name under ``releasenote/notes/`` directory:
 
 ::
 
@@ -102,7 +117,7 @@ A YAML source file is created with a unique name under releasenote/notes/ direct
 	├── notes
 	│   ├── hello-my-change-dcef4b934a670160.yaml
 
-The content are gound into logical sections based in the default template used by reno:
+The content is grouped into logical sections based in the default template used by reno:
 
 ::
 
@@ -118,75 +133,8 @@ The content are gound into logical sections based in the default template used b
 Modify the content in the YAML source file based on
 `reStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_ format.
 
---------------------------
-Closing Out a Bug or Story
---------------------------
-
-If you are modifying a document as a result of a defect or
-feature that is associated with a StoryBoard Story or Launchpad
-Bug, you must take steps to link your submission (Gerrit Review)
-to the story or bug.
-
-To link a story, add the following lines in your
-commit message.
-Be sure to use the actual story ID and task ID with the commit:
-
-* Story: $story_id
-* Task: $task_id
-
-Following is an example that links a Gerrit Review with Story
-2003375 and Task 2444:
-
-::
-
-   Change the tox.ini directory regarding tox.ini dependencies
-
-   Story: 2003375
-   Task: 24444
-
-**NOTE:** You must provide a blank line before the lines
-used to identify the story and the task.
-If you do not provide this line, your submission will not
-link to the Storyboard's story.
-
-To link a bug, add the approprite lines in your commit message.
-Be sure to provide the actual bug numbers:
-
-* Closes-Bug: $bug_id
-* Partial-Bug: $bug_id
-* Related-Bug: $bug_id
-
-If your fix requires multiple commits, use "Partial-Bug"
-for all the commits except the final one.
-For the final commit, use "Closes-Bug".
-
-Following is an example commit message that closes out bug
-1804024:
-
-::
-
-   AIO Hardware Requirements: Updated AIO HW requirements.
-
-   Added Small HW form factor information simplex/duplex
-   AIO hardware requirements.
-
-   Closes-Bug: #1804024
-
-When you associate a story or bug with a Gerrit review, Gerrit
-automatically updates the status of the story or bug once the
-commit is merged.
-Again, be sure to provide a blank line just before the line
-identifying the bug.
-
-You can find more information on the StarlingX code submission
-guidelines on the
-`wiki <https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines>`_.
-
-To see the list of defects against StarlingX, see the
-`Launchpad Application <https://bugs.launchpad.net/starlingx>`_.
-
 ------------------
-Developer Workflow
+Developer workflow
 ------------------
 
 #. Start common development workflow to create your change: "Hello My Change".
@@ -195,7 +143,7 @@ Developer Workflow
 #. Add your change including its release notes and submit for review.
 
 ---------------------
-Release Team Workflow
+Release team workflow
 ---------------------
 
 #. Start development work to prepare the release. This might include a
@@ -203,8 +151,6 @@ Release Team Workflow
 #. Generate the Reno Report.
 #. Add your change and submit for review.
 
-
-
 .. _starlingx/clients: https://opendev.org/starlingx/clients
 .. _starlingx/config: https://opendev.org/starlingx/config
 .. _starlingx/distcloud: https://opendev.org/starlingx/distcloud

doc/source/deploy_install_guides/r1_release/index.rst

@@ -250,7 +250,7 @@ Unload firewall and disable firewall on boot:
 Getting the StarlingX ISO image
 -------------------------------
 
-Follow the instructions from the :doc:`/contributor/build_guide` to build a
+Follow the instructions from the :doc:`/developer_resources/build_guide` to build a
 StarlingX ISO image.
 
 **********

doc/source/developer_resources/build_guide.rst

@@ -2,7 +2,12 @@
 StarlingX Build Guide
 =====================
 
-This section describes the steps for building an ISO image from a StarlingX release.
+This section describes the steps for building an ISO image from a StarlingX
+release.
+
+.. contents::
+   :local:
+   :depth: 1
 
 ------------
 Requirements

doc/source/developer_resources/index.rst

@@ -4,13 +4,10 @@
 Developer Resources
 ===================
 
-StarlingX developer resources provide information to help you understand the
-architecture of the documentation, how to navigate the StarlingX
-source code, and to understand the development process.
-
 .. toctree::
    :maxdepth: 1
 
+   build_guide
    navigate_source_code
    architecture_docs
    starlingx_patching