Update doc contribute guide and api ref page to use
updated repo/project names - updated doc contribute guide to use updated project names - updated doc contribute guide to remove explicit display of project directory structure (it has changed) - update api ref landing page to use updated project names in URL Change-Id: I05779f9ac0c465f6ed928bc68f333e37275dcb4d Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
@@ -4,17 +4,17 @@ REST API Reference
|
||||
|
||||
StarlingX project REST API references:
|
||||
|
||||
* `Bare Metal <stx-metal/index.html>`__
|
||||
* `Configuration <stx-config/index.html>`__
|
||||
* `Distributed Cloud <stx-distcloud/index.html>`__
|
||||
* `Fault Management <stx-fault/index.html>`__
|
||||
* `High Availability <stx-ha/index.html>`__
|
||||
* `NFV <stx-nfv/index.html>`__
|
||||
* `Software Updates <stx-update/index.html>`__
|
||||
* `Bare Metal <metal/index.html>`__
|
||||
* `Configuration <config/index.html>`__
|
||||
* `Distributed Cloud <distcloud/index.html>`__
|
||||
* `Fault Management <fault/index.html>`__
|
||||
* `High Availability <ha/index.html>`__
|
||||
* `NFV <nfv/index.html>`__
|
||||
* `Software Updates <update/index.html>`__
|
||||
|
||||
StarlingX also has API references for the modified OpenStack APIs:
|
||||
|
||||
* `Block Storage v2 <stx-docs/api-ref-blockstorage-v2-cgcs-ext.html>`__
|
||||
* `Compute v2 <stx-docs/api-ref-compute-v2-cgcs-ext.html>`__
|
||||
* `Image v2 <stx-docs/api-ref-image-v2-cgcs-ext.html>`__
|
||||
* `Network v2 <stx-docs/api-ref-networking-v2-cgcs-ext.html>`__
|
||||
* `Block Storage v2 <docs/api-ref-blockstorage-v2-cgcs-ext.html>`__
|
||||
* `Compute v2 <docs/api-ref-compute-v2-cgcs-ext.html>`__
|
||||
* `Image v2 <docs/api-ref-image-v2-cgcs-ext.html>`__
|
||||
* `Network v2 <docs/api-ref-networking-v2-cgcs-ext.html>`__
|
||||
|
||||
@@ -5,11 +5,8 @@ Documentation contributor guide
|
||||
This guide provides information that allows you to contribute to the
|
||||
`StarlingX documentation <https://docs.starlingx.io/>`_.
|
||||
|
||||
The information focuses on what it takes to materially contribute to the
|
||||
StarlingX documentation.
|
||||
Information common to OpenStack workflow, writing styles, and conventions
|
||||
is not included in this guide.
|
||||
You can find that type of information in the
|
||||
is not included in this guide. Instead refer to the
|
||||
`OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
|
||||
|
||||
---------
|
||||
@@ -17,227 +14,99 @@ Locations
|
||||
---------
|
||||
|
||||
StarlingX documentation consists of several types of manuals and is found
|
||||
in the **stx-docs** and **stx-specs** projects (i.e. repositories).
|
||||
in the `starlingx/docs`_ and `starlingx/specs`_ repositories.
|
||||
|
||||
You can clone these repositories by:
|
||||
|
||||
::
|
||||
|
||||
$ git clone https://git.starlingx.io/stx-docs
|
||||
$ git clone https://git.starlingx.io/stx-specs
|
||||
$ git clone https://opendev.org/starlingx/docs
|
||||
$ git clone https://opendev.org/starlingx/specs
|
||||
|
||||
These projects contain hierarchy that organizes the documentation by topic:
|
||||
|
||||
- **Installation Guide**
|
||||
Installation Guide
|
||||
Describes how to install StarlingX onto Bare Metal or into a virtual
|
||||
environment.
|
||||
|
||||
- Describes how to install StarlingX onto Bare Metal or into a virtual
|
||||
environment.
|
||||
This guide is located in **stx-docs/doc/source/installation_guide**.
|
||||
- **Developer Guide**
|
||||
Developer Guide
|
||||
Describes how to build a StarlingX ISO image from the "master" branch.
|
||||
|
||||
- Describes how to build a StarlingX ISO image from the "master" branch.
|
||||
This guide is located in **stx-docs/doc/source/developer_guide**.
|
||||
- **Project Specifications**
|
||||
Project Specifications
|
||||
Describes specifications, specification templates, and processes for
|
||||
submitting a specification.
|
||||
|
||||
- Describes specifications, specification templates, and processes
|
||||
for submitting a specification.
|
||||
This guide is located in **stx-specs/doc/source**.
|
||||
- **REST API Reference**
|
||||
REST API Reference
|
||||
Describes StarlingX APIs.
|
||||
|
||||
- Describes StarlingX APIs.
|
||||
The landing page for the API Reference manuals is located in
|
||||
**stx-docs/doc/source/api-ref**.
|
||||
The RST files that provide content to the API Reference manuals
|
||||
are located in **stx-docs/api-ref/source**.
|
||||
- **Release Notes**
|
||||
Release Notes
|
||||
Provides release-specific information.
|
||||
|
||||
- Provides release-specific information.
|
||||
This guide is located in **stx-docs/doc/source/releasenotes**.
|
||||
- **Contribute**
|
||||
|
||||
- Provides guides on how to contribute to StarlingX API documentation,
|
||||
Release Notes, and general documentation.
|
||||
These guides are located in **stx-docs/doc/source/contributor**.
|
||||
Contribute
|
||||
Provides guides on how to contribute to StarlingX API documentation,
|
||||
release notes, and general documentation.
|
||||
|
||||
--------------------
|
||||
Directory Structures
|
||||
--------------------
|
||||
|
||||
Directory structures vary depending on the type of documentation involved.
|
||||
Basically, you can think of the structure as one or more RST files per
|
||||
book.
|
||||
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.
|
||||
Think of the structure as one or more RST files per book.
|
||||
|
||||
Following is the structure of the **stx-docs** repository:
|
||||
* 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.
|
||||
|
||||
::
|
||||
|
||||
.
|
||||
├── api-ref
|
||||
│ └── source
|
||||
│ ├── api-ref-blockstorage-v2-cgcs-ext.rst
|
||||
│ ├── api-ref-compute-v2-cgcs-ext.rst
|
||||
│ ├── api-ref-image-v2-cgcs-ext.rst
|
||||
│ ├── api-ref-networking-v2-cgcs-ext.rst
|
||||
│ ├── conf.py
|
||||
│ └── index.rst
|
||||
├── doc
|
||||
│ └── source
|
||||
│ ├── api-ref
|
||||
│ │ └── index.rst
|
||||
│ ├── conf.py
|
||||
│ ├── contributor
|
||||
│ │ ├── api_contribute_guide.rst
|
||||
│ │ ├── doc_contribute_guide.rst
|
||||
│ │ ├── index.rst
|
||||
│ │ └── release_note_contribute_guide.rst
|
||||
│ ├── developer_guide
|
||||
│ │ └── index.rst
|
||||
│ ├── index.rst
|
||||
│ ├── installation_guide
|
||||
│ │ ├── controller_storage.rst
|
||||
│ │ ├── dedicated_storage.rst
|
||||
│ │ ├── duplex.rst
|
||||
│ │ ├── index.rst
|
||||
│ │ ├── installation_libvirt_qemu.rst
|
||||
│ │ └── simplex.rst
|
||||
│ └── releasenotes
|
||||
│ └── index.rst
|
||||
├── README.rst
|
||||
├── test-requirements.txt
|
||||
└── tox.ini
|
||||
|
||||
The structure for the API Reference documentation deserves
|
||||
some extra explanation.
|
||||
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 (e.g. **stx-metal**, **stx-config**, and so
|
||||
forth).
|
||||
However, four API Reference RST files do not: "Block Storage",
|
||||
"Compute", "Image", and "Network".
|
||||
These RST files reside in **stx-docs/api-ref/source** as seen
|
||||
in the previous tree diagram.
|
||||
While the **stx-docs/api-ref/source/index.rst** file does exist along
|
||||
side these other four RST files, it does so only because the Sphinx
|
||||
process needs that index file to build out the final web documentation
|
||||
tree.
|
||||
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"
|
||||
* "Compute"
|
||||
* "Image"
|
||||
* "Network".
|
||||
|
||||
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 **stx-docs/doc/source/api-ref/index.rst** file.
|
||||
is in the **/doc/source/api-ref/index.rst** file.
|
||||
|
||||
Here is the structure of the **stx-specs** project:
|
||||
In the `starlingx/specs`_ project, the **/doc/source/index.rst**
|
||||
file is the main landing page for the StarlingX specifications page
|
||||
(<https://docs.starlingx.io/specs/index.html>`_).
|
||||
|
||||
::
|
||||
|
||||
.
|
||||
├── doc
|
||||
│ └── source
|
||||
│ ├── conf.py
|
||||
│ ├── index.rst
|
||||
│ └── specs
|
||||
│ ├── 2019.03
|
||||
│ │ ├── approved -> ../../../../specs/2019.03/approved
|
||||
│ │ ├── implemented -> ../../../../specs/2019.03/implemented
|
||||
│ │ ├── index.rst
|
||||
│ │ └── template.rst -> ../../../../specs/2019.03/approved/STX_Example_Spec.rst
|
||||
│ └── instructions.rst -> ../../../specs/instructions.rst
|
||||
├── README.rst
|
||||
├── specs
|
||||
│ ├── 2019.03
|
||||
│ │ ├── approved
|
||||
│ │ │ ├── containerization-2002840-local-docker-registry.rst
|
||||
│ │ │ ├── containerization-2002843-kubernetes-platform-support.rst
|
||||
│ │ │ ├── containerization_2003907_docker-image-generation.rst
|
||||
│ │ │ ├── containerization-2003908-armada-integration.rst
|
||||
│ │ │ ├── containerization-2003909-helm-chart-overrides.rst
|
||||
│ │ │ ├── containerization-2003910-system-deployment-of-containerized-openstack-infrastructure.rst
|
||||
│ │ │ ├── mirror_2003906_enable_external_mirror.rst
|
||||
│ │ │ ├── multi-os-2003768-refactor-init-config-patches.rst
|
||||
│ │ │ ├── multi-os-2004039-variable-substitution.rst
|
||||
│ │ │ ├── standardize-makefiles-for-multi-os.rst
|
||||
│ │ │ ├── STX_Example_Spec.rst
|
||||
│ │ │ └── sysinv_2002950-decouple-system-configuration-from-inventory.rst
|
||||
│ │ └── implemented
|
||||
│ │ └── _placeholder.rst
|
||||
│ ├── approved
|
||||
│ │ └── containerization-2002844-CEPH-persistent-storage-backend-for-Kubernetes.rst
|
||||
│ ├── instructions.rst
|
||||
│ └── STX_Example_Spec.rst -> 2019.03/approved/STX_Example_Spec.rst
|
||||
├── test-requirements.txt
|
||||
└── tox.ini
|
||||
|
||||
The **stx-specs/docs/source/index.rst** file is the main landing page for the
|
||||
StarlingX specifications page (<https://docs.starlingx.io/specs/index.html>`_).
|
||||
|
||||
The **stx-specs/specs/2019.03** area contains the RST files for approved and
|
||||
The **/specs/2019.03** area contains the RST files for approved and
|
||||
implemented specs.
|
||||
|
||||
-----------------
|
||||
Updating a Manual
|
||||
-----------------
|
||||
|
||||
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.
|
||||
|
||||
As an example, suppose you wanted to update the
|
||||
`Developer Guide <https://docs.starlingx.io/developer_guide/index.html>`_.
|
||||
|
||||
The structure for the Developer Guide is as follows:
|
||||
|
||||
::
|
||||
|
||||
├── doc
|
||||
│ └── source
|
||||
│ ├── developer_guide
|
||||
│ │ └── index.rst
|
||||
|
||||
The content for the manual exists in the **index.rst** file.
|
||||
This file is the landing page and all the content.
|
||||
|
||||
Suppose you needed to update a more complicated manual such as the
|
||||
`Installation Guide <https://docs.starlingx.io/installation_guide/index.html>`_.
|
||||
That manual's source structure is as follows:
|
||||
|
||||
::
|
||||
|
||||
├── doc
|
||||
│ └── source
|
||||
│ ├── installation_guide
|
||||
│ │ ├── controller_storage.rst
|
||||
│ │ ├── dedicated_storage.rst
|
||||
│ │ ├── duplex.rst
|
||||
│ │ ├── index.rst
|
||||
│ │ ├── installation_libvirt_qemu.rst
|
||||
│ │ └── simplex.rst
|
||||
|
||||
The **index.rst** file is the landing page plus the main content for the
|
||||
Installation Guide.
|
||||
The remaining five RST files hold additional content for the guide accessed
|
||||
through links from the landing page.
|
||||
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.
|
||||
|
||||
-----------------
|
||||
Creating a Manual
|
||||
-----------------
|
||||
|
||||
Creating a new manual for **stx-docs** involves minimally providing the
|
||||
**index.rst** file.
|
||||
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
|
||||
**stx-docs/doc/source/my-guide**.
|
||||
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".
|
||||
|
||||
The content for the new manual exists in three files:
|
||||
|
||||
* stx-docs/doc/source/my-guide/index.rst**
|
||||
* stx-docs/doc/source/my-guide/topic_1.rst**
|
||||
* stx-docs/doc/source/my-guide/topic_2.rst**
|
||||
* **/doc/source/my-guide/index.rst**
|
||||
* **/doc/source/my-guide/topic_1.rst**
|
||||
* **/doc/source/my-guide/topic_2.rst**
|
||||
|
||||
Following shows the hierarchy:
|
||||
|
||||
@@ -304,35 +173,14 @@ 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 you can get the new guide to be part
|
||||
of the TOC StarlingX uses when displaying all the documentation
|
||||
(i.e. `StarlingX Documentation <https://docs.starlingx.io/>`_).
|
||||
This section describes how to add your new guide to the table of contents in the
|
||||
documentation site.
|
||||
|
||||
The **stx-docs/doc/source/index.rst** file contains the structure
|
||||
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 TOC.
|
||||
Following is the updated file that shows the example guide
|
||||
included.
|
||||
The "my_guide/index" line ensures the new guide is included
|
||||
in the TOC along with the existing guides:
|
||||
|
||||
::
|
||||
|
||||
--------
|
||||
Sections
|
||||
--------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
installation_guide/index
|
||||
developer_guide/index
|
||||
Project Specifications <https://docs.starlingx.io/specs/>
|
||||
api-ref/index
|
||||
releasenotes/index
|
||||
contributor/index
|
||||
my_guide/index
|
||||
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
|
||||
@@ -414,109 +262,27 @@ following command:
|
||||
|
||||
$ tox -e docs
|
||||
|
||||
The resulting directories and HTML files looks like:
|
||||
The resulting HTML files will be located in the **/doc/build**
|
||||
directory:
|
||||
|
||||
::
|
||||
|
||||
stx-docs/doc/
|
||||
starlingx/docs/doc/
|
||||
├── build
|
||||
│ ├── doctrees
|
||||
│ │ ├── api-ref
|
||||
│ │ │ └── index.doctree
|
||||
│ │ ├── contributor
|
||||
│ │ │ ├── api_contribute_guide.doctree
|
||||
│ │ │ ├── doc_contribute_guide.doctree
|
||||
│ │ │ ├── index.doctree
|
||||
│ │ │ └── release_note_contribute_guide.doctree
|
||||
│ │ ├── developer_guide
|
||||
│ │ │ └── index.doctree
|
||||
│ │ ├── environment.pickle
|
||||
│ │ ├── index.doctree
|
||||
│ │ ├── installation_guide
|
||||
│ │ │ ├── controller_storage.doctree
|
||||
│ │ │ ├── dedicated_storage.doctree
|
||||
│ │ │ ├── duplex.doctree
|
||||
│ │ │ ├── index.doctree
|
||||
│ │ │ ├── installation_libvirt_qemu.doctree
|
||||
│ │ │ └── simplex.doctree
|
||||
│ │ ├── my_guide
|
||||
│ │ │ ├── index.doctree
|
||||
│ │ │ ├── topic_1.doctree
|
||||
│ │ │ ├── topic_2.doctree
|
||||
│ │ └── releasenotes
|
||||
│ │ └── index.doctree
|
||||
│ └── html
|
||||
│ ├── api-ref
|
||||
│ │ └── index.html
|
||||
│ ├── contributor
|
||||
│ │ ├── api_contribute_guide.html
|
||||
│ │ ├── doc_contribute_guide.html
|
||||
│ │ ├── index.html
|
||||
│ │ └── release_note_contribute_guide.html
|
||||
│ ├── developer_guide
|
||||
│ │ └── index.html
|
||||
│ ├── genindex.html
|
||||
│ ├── index.html
|
||||
│ ├── installation_guide
|
||||
│ │ ├── controller_storage.html
|
||||
│ │ ├── dedicated_storage.html
|
||||
│ │ ├── duplex.html
|
||||
│ │ ├── index.html
|
||||
│ │ ├── installation_libvirt_qemu.html
|
||||
│ │ └── simplex.html
|
||||
│ ├── my_guide
|
||||
│ │ ├── index.html
|
||||
│ │ ├── topic_1.html
|
||||
│ │ ├── topic_2.html
|
||||
│ ├── objects.inv
|
||||
│ ├── releasenotes
|
||||
│ │ └── index.html
|
||||
│ ├── search.html
|
||||
│ ├── searchindex.js
|
||||
│ ├── _sources
|
||||
│ │ ├── api-ref
|
||||
│ │ │ └── index.rst.txt
|
||||
│ │ ├── contributor
|
||||
│ │ │ ├── api_contribute_guide.rst.txt
|
||||
│ │ │ ├── doc_contribute_guide.rst.txt
|
||||
│ │ │ ├── index.rst.txt
|
||||
│ │ │ └── release_note_contribute_guide.rst.txt
|
||||
│ │ ├── developer_guide
|
||||
│ │ │ └── index.rst.txt
|
||||
│ │ ├── index.rst.txt
|
||||
│ │ ├── installation_guide
|
||||
│ │ │ ├── controller_storage.rst.txt
|
||||
│ │ │ ├── dedicated_storage.rst.txt
|
||||
│ │ │ ├── duplex.rst.txt
|
||||
│ │ │ ├── index.rst.txt
|
||||
│ │ │ ├── installation_libvirt_qemu.rst.txt
|
||||
│ │ │ └── simplex.rst.txt
|
||||
│ │ ├── my_guide
|
||||
│ │ │ ├── index.rst.txt
|
||||
│ │ │ ├── topic_1.rst.txt
|
||||
│ │ │ ├── topic_2.rst.txt
|
||||
│ │ │ ├── topic_3.rst.txt
|
||||
│ │ │ ├── topic_4.rst.txt
|
||||
│ │ │ └── topic_5.rst.txt
|
||||
│ │ └── releasenotes
|
||||
│ │ └── index.rst.txt
|
||||
│ └── _static
|
||||
|
||||
...
|
||||
|
||||
├── Makefile
|
||||
├── requirements.txt
|
||||
├── setup.cfg
|
||||
├── setup.py
|
||||
|
||||
----------------------------------
|
||||
Viewing the Rendered Documentation
|
||||
----------------------------------
|
||||
|
||||
To view the rendered document in a browser, open up
|
||||
To view the rendered documentation in a browser, open up
|
||||
the **index.html** file in your browser.
|
||||
For the new example guide, the file is
|
||||
**stx-docs/doc/build/my_guide/index.html**.
|
||||
|
||||
**NOTE:** The PDF build uses a different tox environment and is
|
||||
currently not supported for StarlingX.
|
||||
|
||||
|
||||
.. _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
|
||||
Reference in New Issue
Block a user