20269cc03f
- 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>
434 lines
10 KiB
ReStructuredText
434 lines
10 KiB
ReStructuredText
===============================
|
|
Documentation Contributor Guide
|
|
===============================
|
|
|
|
This section describes the guidelines for contributing to the StarlingX
|
|
documentation.
|
|
|
|
.. contents::
|
|
: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:
|
|
|
|
* `Writing style`_
|
|
* `RST conventions`_
|
|
|
|
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:
|
|
|
|
::
|
|
|
|
Brief description of change.
|
|
|
|
Detailed description of change.
|
|
|
|
Story: $story_id
|
|
Task: $task_id
|
|
|
|
Or, to link to the bug that the review fixes:
|
|
|
|
::
|
|
|
|
Brief description of bug fix.
|
|
|
|
Detailed description of bug fix.
|
|
|
|
Closes-Bug: $bug_id
|
|
|
|
-----------------
|
|
Docs organization
|
|
-----------------
|
|
|
|
Documentation for StarlingX is organized into the following sections:
|
|
|
|
:doc:`/introduction/index`
|
|
Overview of the StarlingX project.
|
|
|
|
:doc:`/deploy_install_guides/index`
|
|
Release-specific installation and deployment guides.
|
|
|
|
:doc:`/configuration/index`
|
|
Configuration references for post-installation StarlingX system configuration.
|
|
|
|
:doc:`/operations/index`
|
|
System administration and maintenance guides.
|
|
|
|
:doc:`/api-ref/index`
|
|
REST API references for the StarlingX project. For additional information about
|
|
where REST API documentation is located, see `API documentation`_.
|
|
|
|
: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.
|
|
|
|
-------------
|
|
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.
|
|
|
|
* Use Title Case for page titles. For example:
|
|
|
|
::
|
|
|
|
===============================
|
|
Documentation Contributor Guide
|
|
===============================
|
|
|
|
* Start section titles with an action verb, but not a gerund (word that ends with -ing). For example:
|
|
|
|
::
|
|
|
|
------------------
|
|
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:**
|
|
|
|
::
|
|
|
|
:abbr:`CPU (Central Processing Unit)`
|
|
|
|
**Output:**
|
|
|
|
:abbr:`CPU (Central Processing Unit)`
|
|
|
|
************
|
|
Code samples
|
|
************
|
|
|
|
Format code snippets as standalone literal blocks.
|
|
|
|
**Input:**
|
|
|
|
::
|
|
|
|
::
|
|
|
|
ping 8.8.8.8
|
|
|
|
**Output:**
|
|
|
|
::
|
|
|
|
ping 8.8.8.8
|
|
|
|
********
|
|
Commands
|
|
********
|
|
|
|
Format commands using the Sphinx ``command`` role.
|
|
|
|
**Input:**
|
|
|
|
::
|
|
|
|
:command:`system help`
|
|
|
|
**Output:**
|
|
|
|
Use the :command:`system help` command for the full list of options.
|
|
|
|
****************
|
|
Cross-references
|
|
****************
|
|
|
|
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 <http://docutils.sourceforge.net/docs/user/rst/quickref.html#internal-hyperlink-targets>`_
|
|
|
|
**Input:**
|
|
|
|
::
|
|
|
|
.. _my_named_target:
|
|
|
|
~~~~~~~~~~
|
|
My section
|
|
~~~~~~~~~~
|
|
|
|
This is the section we want to reference.
|
|
|
|
...
|
|
|
|
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.
|
|
|
|
|
|
***************
|
|
Inline elements
|
|
***************
|
|
|
|
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.
|
|
|