Documentation Contributor Guide

This section describes the guidelines for contributing to the StarlingX documentation.


The StarlingX documentation uses reStructuredText (RST) markup syntax with Sphinx extensions. It uses the same contribution setup and workflow as the OpenStack documentation.

Setup for contribution

Follow the OpenStack instructions for setting up for contribution.

Make a change

  1. Make changes following the OpenStack instructions for:

    1. Starting a change

    2. Committing a change.


      StarlingX requires the use of a Signed-off-by header. Use the -s option with git commit.

  2. When writing documentation, follow Writing style and RST conventions.

  3. Build the documentation locally to verify your changes before committing. Follow the OpenStack instructions for Building documentation.

  4. If needed, follow up with edits to your patch following the OpenStack instructions for Responding to requests.

Find tasks and help needed

If you are looking for work to complete:

If you make a contribution that has an the associated story, task, or bug in the comment, link to the related story or bug as described in the Code Submission Guidelines.

Docs organization

Documentation for StarlingX is organized into the following sections:


Overview of the StarlingX project.

Installation Guides

Release-specific installation and deployment guides.


Configuration references for post-installation StarlingX system configuration.

Operation Guides

System administration and maintenance guides.

REST API Reference

REST API references for the StarlingX project. For additional information about where REST API documentation is located, see API documentation.

CLI Reference

Reference for the StarlingX project command line interface (CLI).

Developer Resources

Resources for developers using or building StarlingX.

Release Notes

Release notes for all StarlingX releases.

Contributor Guides

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.

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 API Documentation Contributor Guide.

Spec documentation

Spec documentation is found in the Starlingx specs project.

The specs/2019.03 directory contains the documentation files for approved and implemented specs.

Writing style

StarlingX documentation follows many (but not all!) of the writing style guidelines described in the OpenStack documentation writing style guide. Differences between the StarlingX and OpenStack practices are highlighted below.

  • Use Title Case for page titles. For example:

    Documentation Contributor Guide
  • Start section titles with an action verb. Do not use a gerund (word that ends with -ing). For example:

    Configure endpoint

Create rST Files

Use the tox -e newfile command to create new rST files.

About this task

All rST files created in StarlingX documentation repositories must have the following characteristics:

  • They must have unique file names.

  • They must have rST labels at the beginning of the files that match the file names.


These rules apply to index files as well as those containing user documentation.

A utility is available for use from within each documentation repository you have installed to generate uniquely named files for you.


You must have uuidgen installed on your system. This program is included by default on most modern Linux distributions. If it is not installed, consult your distribution’s documentation for instructions.


  1. Change to the directory where you wish to create a new topic.

    Typically, this will be below the doc/source directory of the repository.

  2. Run the following tox command.

    tox -e newfile
  3. When prompted, enter a title for the new topic.

     You are about to create a new reStructuredText file in
     or a content fragment file in doc/source/_includes
     If this is not what you want, press CTL-C to quit and change to the directory
     you want to create the file in.
     Enter a title for the new topic. The file name and topic label used for
     linking will be based on this value.
     Topic title:
    1. Review the directory (an example is highlighted above) that the utility will create the new file in.


      This does not apply if you choose to create a content fragment using the f option when prompted. In that case, the file will be saved to doc/source/_includes regardless of your current working directory.

    2. If this is not correct, press CTL-C to quit, change to the correct directory, and run the command again; otherwise, type the topic title and press ENTER.

  4. When prompted, select the type of rST stub file you want to create.

    Thanks. Now choose a topic type. Enter one of the following characters:
    t) A task topic. Will contain the outline of a procedure.
    i) An index.
    r) A reference topic. Will contain a minimal list-table definition.
    g) A minimal generic topic.
    f) A content fragment included in an rST file. Will be saved to doc/source/_includes.
    Topic type:

    Each option creates a stub file with different templated content useful for getting started. Press the corresponding key.


The new rST file is created.

The title used in the new rST file matches what you typed exactly. However, some changes have been made to the file name and topic label.

For example, if you entered Architectural Considerations! as a title, listing the directory will show a file similar to the following:


The following changes were made.

  • All alphabetical characters were converted to lower case.

  • All spaces and special characters, such as the ! were replaced by dashes.

  • A final dash and 12 digit random string were appended to the file name.

  • The extension .rst was added for all options except f, in which case the extension .rest was added.

  • If you chose to create an index file by selecting i when prompted, index- was prepended to the file name.

Examining the file reveals that the label matches the file name, while the title is preserved as typed. No label was added if you selected f.

cat architectural-considerations--d9dd4c105700.rst
.. _architectural-considerations--d9dd4c105700:

Architectural Considerations!

.. content here

When you reference this file in toctree and ref directives, use the file name/label string like this: architectural-considerations--d9dd4c105700

RST conventions

StarlingX documentation follows many (but not all!) of the RST conventions described in the OpenStack documentation RST conventions guide. 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:

RST quick reference


Define acronym at first instance on page. After definition, use acronym only.


:abbr:`CPU (Central Processing Unit)`



Code samples

Format code snippets as standalone literal blocks.







Format commands using the Sphinx command role.


:command:`system help`


Use the system help command for the full list of options.


Cross-reference to arbitrary locations in a document using the ref role and a named target. Named targets must precede a section heading. For more information on references, see Internal Hyperlink Targets.


.. _my_named_target:

My section

This is the section we want to reference.


This is the reference to :ref:`my_named_target`.


My section

This is the section we want to reference.

This is the reference to My section.

Information blocks

Emphasize information using notices (an admonition in Sphinx). Different types of notices exist to emphasize degrees of information importance.


.. 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.



Use a note for a generic message.

See also

Use seealso for extra but helpful information.


Use important for details that can be easily missed, but should not be ignored by a user and are valuable before proceeding.


Use warning to call out information the user must understand to avoid negative consequences.

Inline elements

Format most inline elements such as filenames and paths, code fragments, parameters, or options with double back ticks.




Open the /path/to/ file.

Optionally pass the --option with the command.

Refer to the OpenStack Inline elements guide for markup for other inline elements.


Use a bulleted list for a sequence of items whose order does not matter, such as a list of features.


* Banana
* Apple
* Orange


  • Banana

  • Apple

  • Orange

Use an enumerated list for a sequence of items whose order matters, such as in an ordered sequence of installation steps.


#. Wash apple.
#. Peel apple.
#. Eat apple.


  1. Wash apple.

  2. Peel apple.

  3. Eat apple.

Use a definition list for an unordered list where each item has a short definition, such as term/definition pairs.


Command A
  Description of command A.

Command B
  Description of command B.


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:

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