From 20269cc03f27d9b174ffeed889ec33f95fdcc902 Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Fri, 13 Dec 2019 14:47:08 -0800 Subject: [PATCH] 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 --- .../contributor/api_contribute_guide.rst | 260 +++----- .../contributor/development_process.rst | 4 +- .../contributor/doc_contribute_guide.rst | 583 +++++++++++------- doc/source/contributor/index.rst | 50 +- .../release_note_contribute_guide.rst | 172 ++---- .../r1_release/index.rst | 2 +- .../build_guide.rst | 7 +- doc/source/developer_resources/index.rst | 5 +- 8 files changed, 547 insertions(+), 536 deletions(-) rename doc/source/{contributor => developer_resources}/build_guide.rst (96%) diff --git a/doc/source/contributor/api_contribute_guide.rst b/doc/source/contributor/api_contribute_guide.rst index 9b917e85b..26642f9cd 100644 --- a/doc/source/contributor/api_contribute_guide.rst +++ b/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 `_. + +.. contents:: + :local: + :depth: 1 --------- Locations --------- -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. 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 API Reference documentation exists in the following projects: +* `starlingx/config`_: StarlingX System Configuration Management +* `starlingx/docs`_: StarlingX Documentation -- `starlingx/config`_: StarlingX System Configuration Management -- `starlingx/docs`_: StarlingX Documentation - - - *stx-python-cinderclient* // only StarlingX-specific + * *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/fault`_: StarlingX Fault Management -- `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service +* `starlingx/distcloud`_: StarlingX Distributed Cloud +* `starlingx/fault`_: StarlingX Fault Management +* `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 -StarlingX project repository is fixed. Here is an example showing -`starlingx/config`_ StarlingX System Configuration Management +The directory structure of the API reference documentation under each +StarlingX project repository is fixed. This example shows the `starlingx/config`_ +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 - HTML files for the API reference -- **.zuul.yaml** modifications to add the jobs to build and publish the - api-ref document -- **api-ref/source** directory creation to store your API Reference - project directory -- **api-ref/source/conf.py** configuration file to determine the HTML - theme, Sphinx extensions and project information -- **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 +``.gitignore`` + Modifications to ignore the building directories and HTML files for the API + reference. + +``.zuul.yaml`` + Modifications to add jobs to build and publish the ``api-ref`` document. + +``api-ref/source`` + Directory created to store your API Reference project directory. + +``api-ref/source/conf.py`` + Configuration file to set the HTML theme, Sphinx extensions, and project + information. + +``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 -source files that document the API operations under the same API -Reference documentation project directory. The following shows the RST -source file for the `starlingx/config`_ StarlingX System Configuration -Management: Configuration API v1 +Once the API documentation service has been enabled, create the RST source files +that document the API operations under the same API reference documentation +project directory. The following example shows the RST source file for the +`starlingx/config`_ StarlingX System Configuration 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, -you add the **index.rst** file. This file provides captioning, a brief -description of the document, and the table-of-contents structure with -depth restrictions. The **index.rst** file resides in the same folder as -the RST source file. - -Here is an example using the `starlingx/config`_ StarlingX System -Configuration Management: Configuration API v1: +After providing the RST source file as shown in the previous example, add the +``index.rst`` file. This file provides captioning, a brief description of the +document, and the Table-of-Contents structure with depth restrictions. The +``index.rst`` file is located in the same folder as the RST source file: :: @@ -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 -**index.rst** file used in the `starlingx/config`_: +The syntax of the ``index.rst`` file is fixed. The following example shows the +``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 -**index.rst** file: +The ``index.rst`` file contains: -- **Reference title:** Literal title that is used in the rendered - document. In this case it is "stx-config API Reference". -- **Reference summary:** Literal summary of the rendered document. In - this case it is "StarlingX System Configuration Management". -- **Table-of-Contents tree structure and depth parameters:** 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. +``Reference title`` + Literal title that is used in the rendered document. In this case it is + "stx-config API Reference". + +``Reference summary`` + Literal summary of the rendered document. In this case it is + "StarlingX System Configuration Management". + +``Table-of-Contents tree structure and depth parameters`` + 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 -(e.g. **api-ref-sys-v1-config.rst**). +This section describes the syntax for each REST method in the RST source file +(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 ] } - - ------------------------------------- -Building the Reference Documentation ------------------------------------- +--------------------------------- +Build 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 +----------------------------------------- --------------------------- -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: - -* 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 `_. - -To see the list of defects against StarlingX, see the -`Launchpad Application `_. - --------------------------------------------- -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. - - - +To view the rendered HTML API reference document in a browser, open up +the ``index.html`` file. .. _starlingx/config: https://opendev.org/starlingx/config .. _starlingx/docs: https://opendev.org/starlingx/docs diff --git a/doc/source/contributor/development_process.rst b/doc/source/contributor/development_process.rst index b5070288c..c2e829abb 100644 --- a/doc/source/contributor/development_process.rst +++ b/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 diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index a1144717a..d7c20b2ca 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/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 -`StarlingX documentation `_. +This section describes the guidelines for contributing to the StarlingX +documentation. -Information common to OpenStack workflow, writing styles, and conventions -is not included in this guide. Instead refer to the +.. 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 `_. ---------- -Locations ---------- +When writing documentation, follow the StarlingX documentation guidelines: -StarlingX documentation consists of several types of manuals and is found -in the `starlingx/docs`_ and `starlingx/specs`_ repositories. +* `Writing style`_ +* `RST conventions`_ -You can clone these repositories by: +Verify that your changes render properly by `building the documentation locally `_. + +****************** +Contribute content +****************** + +If you are looking for work to complete, review these reports: + +* Refer to the `StarlingX documentation StoryBoard `_ 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 `_. + + +When creating a Gerrit review, link the associated story, task, or bug in the +comment, according to `Starlingx Code Submission Guidelines `_. + +For example, link a story and task in a comment: :: - $ git clone https://opendev.org/starlingx/docs.git - $ git clone https://opendev.org/starlingx/specs.git + Brief description of change. -These projects contain hierarchy that organizes the documentation by topic: + Detailed description of change. -Installation Guide - Describes how to install StarlingX onto Bare Metal or into a virtual - environment. + Story: $story_id + Task: $task_id -Developer Guide - Describes how to build a StarlingX ISO image from the "master" branch. +Or, to link to the bug that the review fixes: -Project Specifications - Describes specifications, specification templates, and processes for - submitting a specification. +:: -REST API Reference - Describes StarlingX APIs. + Brief description of bug fix. -Release Notes - Provides release-specific information. + Detailed description of bug fix. -Contribute - Provides guides on how to contribute to StarlingX API documentation, - release notes, and general documentation. + Closes-Bug: $bug_id --------------------- -Directory Structures --------------------- +----------------- +Docs organization +----------------- -Directory structures vary depending on the type of documentation involved. -Think of the structure as one or more RST files per book. +Documentation for StarlingX is organized into the following sections: -* A simple book consists of a single **index.rst** file. -* A more complicated book could consist of an **index.rst** file as the book's - landing page and a set of additional RST files for major sections of the book. +:doc:`/introduction/index` + Overview of the StarlingX project. -The structure for the API Reference documentation deserves some extra explanation. -Most RST files for the API Reference content reside in top-level -StarlingX repositories, for example `starlingx/metal`_ or `starlingx/config`_. -However, four API Reference RST files reside in `starlingx/docs`_, -in **/api-ref/source**: +:doc:`/deploy_install_guides/index` + Release-specific installation and deployment guides. -* "Block Storage" -* "Compute" -* "Image" -* "Network". +:doc:`/configuration/index` + Configuration references for post-installation StarlingX system configuration. -While there is a **/api-ref/source/index.rst** file along -side these other four RST files, it exists only because the Sphinx process -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. +:doc:`/operations/index` + System administration and maintenance guides. -In the `starlingx/specs`_ project, the **/doc/source/index.rst** -file is the main landing page for the StarlingX specifications page -(`_). +:doc:`/api-ref/index` + REST API references for the StarlingX project. For additional information about + 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 `_. + +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 `_. + +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 -source file, make your modifications, test them (i.e. build the manual), and -then submit the changes to Gerrit for approval. +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. ------------------ -Creating a Manual ------------------ +* Use Title Case for page titles. For example: -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 -links to additional complicated topics: "Topic 1" and -"Topic 2". + =============================== + Documentation Contributor Guide + =============================== -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 `_. 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 `_ +* `reStructuredText primer `_ + +------------------- +RST quick reference +------------------- + +.. contents:: + :local: + :depth: 1 + +******** +Acronyms +******** + +Define acronym at first instance on page. After definition, use acronym only. + +**Input:** :: - ├── doc - │   └── source - │   ├── my_guide - │   │   ├── index.rst - │   │   ├── topic_1.rst - │   │   ├── topic_2.rst + :abbr:`CPU (Central Processing Unit)` +**Output:** ------------------------ -Creating the Index File ------------------------ +:abbr:`CPU (Central Processing Unit)` -The **index.rst** file provides captioning, a brief -description of the document, and the table-of-contents (TOC) structure -with instructions on how to display or hide sub-topics. +************ +Code samples +************ -The syntax of the **index.rst** file is fixed. Following shows the -sample **index.rst** file for the new guide: +Format code snippets as standalone literal blocks. + +**Input:** :: - ======== - My Guide - ======== + :: - The new guide. + ping 8.8.8.8 - - :ref:`Topic 1 ` - - :ref:`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: +**Output:** :: - 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 -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. +Format commands using the Sphinx ``command`` role. -To link a bug, add the appropriate 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: +**Input:** :: - AIO Hardware Requirements: Updated AIO HW requirements. + :command:`system help` - Added Small HW form factor information simplex/duplex - AIO hardware requirements. +**Output:** - 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 -commit is merged. -Again, be sure to provide a blank line just before the line -identifying the bug. +**************** +Cross-references +**************** -You can find more information on the StarlingX code submission -guidelines on the -`wiki `_. +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 `_ -To see the list of defects against StarlingX, see the -`Launchpad Application `_. - --------------------------- -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: +**Input:** :: - starlingx/docs/doc/ - ├── build - │   └── html + .. _my_named_target: ----------------------------------- -Viewing the Rendered Documentation ----------------------------------- + ~~~~~~~~~~ + My section + ~~~~~~~~~~ -To view the rendered documentation in a browser, open up -the **index.html** file in your browser. + This is the section we want to reference. -**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 -.. _starlingx/metal: https://opendev.org/starlingx/metal -.. _starlingx/config: https://opendev.org/starlingx/config \ No newline at end of file +*************** +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 `_ +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. + diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 78884b441..20b11ad8f 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,16 +1,13 @@ .. _contribute: -========== -Contribute -========== +================== +Contributor Guides +================== -The following guides provide detailed instructions on the contribution workflow -and conventions to be considered when contributing to the StarlingX documentation. +Welcome to the StarlingX community! We are glad you are here. -StarlingX utilizes tooling and CI/CD environments from the OpenStack -Foundation. The source is hosted on `OpenDev's Git server`_. - -.. _`OpenDev's Git server`: https://opendev.org/starlingx +If you are new to the project, take a moment to review the +`StarlingX wiki `_. --------------------------- 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 `_. Additional StarlingX-specific resources are listed below. .. toctree:: :maxdepth: 1 development_process - ---------------- -Build StarlingX ---------------- - -Refer to the StarlingX Build Guide for instructions on how to build a StarlingX -ISO image. - -.. toctree:: - :maxdepth: 1 - - build_guide + Code Submission Guidelines -------------------- Additional resources -------------------- -Additional information about contributing to OpenStack documentation can be found -in the following guides: - -* `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 +* `StarlingX wiki `_ +* :doc:`/developer_resources/index` \ No newline at end of file diff --git a/doc/source/contributor/release_note_contribute_guide.rst b/doc/source/contributor/release_note_contribute_guide.rst index 4da9dfcf9..319c81ff2 100644 --- a/doc/source/contributor/release_note_contribute_guide.rst +++ b/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/config`_: StarlingX System Configuration Management -- `starlingx/distcloud`_: StarlingX Distributed Cloud -- `starlingx/distcloud-client`_: StarlingX Distributed Cloud Client -- `starlingx/fault`_: StarlingX Fault Management -- `starlingx/gui`_: StarlingX Horizon plugins for new StarlingX services -- `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service Management -- `starlingx/integ`_: StarlingX Integration and Packaging -- `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware Maintenance -- `starlingx/nfv`_: StarlingX NFVI Orchestration -- `starlingx/tools`_: StarlingX Build Tools -- `starlingx/update`_: StarlingX Installation/Update/Patching/Backup/Restore -- `starlingx/upstream`_: StarlingX Upstream Packaging +* `starlingx/clients`_: StarlingX Client Libraries +* `starlingx/config`_: StarlingX System Configuration Management +* `starlingx/distcloud`_: StarlingX Distributed Cloud +* `starlingx/distcloud-client`_: StarlingX Distributed Cloud Client +* `starlingx/fault`_: StarlingX Fault Management +* `starlingx/gui`_: StarlingX Horizon plugins for new StarlingX services +* `starlingx/ha`_: StarlingX High Availability/Process Monitoring/Service Management +* `starlingx/integ`_: StarlingX Integration and Packaging +* `starlingx/metal`_: StarlingX Bare Metal and Node Management, Hardware Maintenance +* `starlingx/nfv`_: StarlingX NFVI Orchestration +* `starlingx/tools`_: StarlingX Build Tools +* `starlingx/update`_: StarlingX Installation/Update/Patching/Backup/Restore +* `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 -Configuration Management: +repository is fixed. This example shows the ``stx-confi`` project: :: @@ -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 - for the Release Notes -- **.zuul.yaml** modifications to add the jobs to build and publish the api-ref - document -- **releasenotes/notes/** directory creation to store your release notes files - in YAML format -- **releasenotes/source** directory creation to store your API Reference project - directory -- **releasenotes/source/conf.py** configuration file to determine the HTML theme, - Sphinx extensions and project information -- **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 +``.gitignore`` + Modifications to ignore the building directories and HTML files for the + release notes. + +``.zuul.yaml`` + Modifications to add jobs to build and publish the ``api-ref`` document. + +``releasenotes/notes`` + Directory created to store your release notes files in YAML format. + +``releasenotes/source`` + Directory created to store your API reference project directory. + +``releasenotes/source/conf.py`` + Configuration file to determine the HTML theme, Sphinx extensions, and + project information. + +``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 -Configuration Management: +The following shows the YAML source file for the stx-config project: + `Release Summary R1.0 `_ :: @@ -89,12 +104,12 @@ Configuration Management: ├── notes │ └── release-summary-6738ff2f310f9b57.yaml - -To create a new release note that document your code changes via tox newnote environment: +To create a new release note that documents your code changes via the +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 `_ 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 `_. - -To see the list of defects against StarlingX, see the -`Launchpad Application `_. - ------------------ -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 diff --git a/doc/source/deploy_install_guides/r1_release/index.rst b/doc/source/deploy_install_guides/r1_release/index.rst index 2f4558de2..7bf658e28 100644 --- a/doc/source/deploy_install_guides/r1_release/index.rst +++ b/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. ********** diff --git a/doc/source/contributor/build_guide.rst b/doc/source/developer_resources/build_guide.rst similarity index 96% rename from doc/source/contributor/build_guide.rst rename to doc/source/developer_resources/build_guide.rst index cc2dd6a8c..ca9972727 100644 --- a/doc/source/contributor/build_guide.rst +++ b/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 diff --git a/doc/source/developer_resources/index.rst b/doc/source/developer_resources/index.rst index d12f4cb20..c3c0bc823 100644 --- a/doc/source/developer_resources/index.rst +++ b/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