starlingx/docs
Code Issues Proposed changes

Update doc contribute guide and api ref page to use

Browse Source 
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
2019-08-28 16:38:49 -07:00
parent f7bce640c8
commit 7edaf9f52e
2 changed files with 75 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
doc/source/api-ref/index.rst
View File

@@ -4,17 +4,17 @@ REST API Reference
StarlingX project REST API references: StarlingX project REST API references:
* `Bare Metal <stx-metal/index.html>`__ * `Bare Metal <metal/index.html>`__
* `Configuration <stx-config/index.html>`__ * `Configuration <config/index.html>`__
* `Distributed Cloud <stx-distcloud/index.html>`__ * `Distributed Cloud <distcloud/index.html>`__
* `Fault Management <stx-fault/index.html>`__ * `Fault Management <fault/index.html>`__
* `High Availability <stx-ha/index.html>`__ * `High Availability <ha/index.html>`__
* `NFV <stx-nfv/index.html>`__ * `NFV <nfv/index.html>`__
* `Software Updates <stx-update/index.html>`__ * `Software Updates <update/index.html>`__
StarlingX also has API references for the modified OpenStack APIs: StarlingX also has API references for the modified OpenStack APIs:
* `Block Storage v2 <stx-docs/api-ref-blockstorage-v2-cgcs-ext.html>`__ * `Block Storage v2 <docs/api-ref-blockstorage-v2-cgcs-ext.html>`__
* `Compute v2 <stx-docs/api-ref-compute-v2-cgcs-ext.html>`__ * `Compute v2 <docs/api-ref-compute-v2-cgcs-ext.html>`__
* `Image v2 <stx-docs/api-ref-image-v2-cgcs-ext.html>`__ * `Image v2 <docs/api-ref-image-v2-cgcs-ext.html>`__
* `Network v2 <stx-docs/api-ref-networking-v2-cgcs-ext.html>`__ * `Network v2 <docs/api-ref-networking-v2-cgcs-ext.html>`__

362
doc/source/contributor/doc_contribute_guide.rst
View File

@@ -5,11 +5,8 @@ Documentation contributor guide
This guide provides information that allows you to contribute to the This guide provides information that allows you to contribute to the
`StarlingX documentation <https://docs.starlingx.io/>`_. `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 Information common to OpenStack workflow, writing styles, and conventions
is not included in this guide. is not included in this guide. Instead refer to the
You can find that type of information in the
`OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_. `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 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: You can clone these repositories by:
:: ::
$ git clone https://git.starlingx.io/stx-docs $ git clone https://opendev.org/starlingx/docs
$ git clone https://git.starlingx.io/stx-specs $ git clone https://opendev.org/starlingx/specs
These projects contain hierarchy that organizes the documentation by topic: 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 Developer Guide
environment. Describes how to build a StarlingX ISO image from the "master" branch.
This guide is located in **stx-docs/doc/source/installation_guide**.
- **Developer Guide**
- Describes how to build a StarlingX ISO image from the "master" branch. Project Specifications
This guide is located in **stx-docs/doc/source/developer_guide**. Describes specifications, specification templates, and processes for
- **Project Specifications** submitting a specification.
- Describes specifications, specification templates, and processes REST API Reference
for submitting a specification. Describes StarlingX APIs.
This guide is located in **stx-specs/doc/source**.
- **REST API Reference**
- Describes StarlingX APIs. Release Notes
The landing page for the API Reference manuals is located in Provides release-specific information.
**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**
- Provides release-specific information. Contribute
This guide is located in **stx-docs/doc/source/releasenotes**. Provides guides on how to contribute to StarlingX API documentation,
- **Contribute** release notes, and general documentation.
- 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**.
-------------------- --------------------
Directory Structures Directory Structures
-------------------- --------------------
Directory structures vary depending on the type of documentation involved. Directory structures vary depending on the type of documentation involved.
Basically, you can think of the structure as one or more RST files per Think of the structure as one or more RST files per book.
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.
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.
:: The structure for the API Reference documentation deserves some extra explanation.
.
├── 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.
Most RST files for the API Reference content reside in top-level Most RST files for the API Reference content reside in top-level
StarlingX repositories (e.g. **stx-metal**, **stx-config**, and so StarlingX repositories, for example `starlingx/metal`_ or `starlingx/config`_.
forth). However, four API Reference RST files reside in `starlingx/docs`_,
However, four API Reference RST files do not: "Block Storage", in **/api-ref/source**:
"Compute", "Image", and "Network".
These RST files reside in **stx-docs/api-ref/source** as seen * "Block Storage"
in the previous tree diagram. * "Compute"
While the **stx-docs/api-ref/source/index.rst** file does exist along * "Image"
side these other four RST files, it does so only because the Sphinx * "Network".
process needs that index file to build out the final web documentation
tree. 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 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>`_).
:: The **/specs/2019.03** area contains the RST files for approved and
.
├── 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
implemented specs. implemented specs.
----------------- -----------------
Updating a Manual Updating a Manual
----------------- -----------------
If you need to update an existing manual, you need to find the If you need to update an existing manual, you need to find the appropriate RST
appropriate RST source file, make your modifications, test them source file, make your modifications, test them (i.e. build the manual), and
(i.e. build the manual), and then submit the changes to Gerrit then submit the changes to Gerrit for approval.
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.
----------------- -----------------
Creating a Manual Creating a Manual
----------------- -----------------
Creating a new manual for **stx-docs** involves minimally providing the Creating a new manual involves at minimum providing a new **index.rst** file.
**index.rst** file.
If the manual is more complex with additional content outside of the If the manual is more complex with additional content outside of the
**index.rst** file, you need to provide additional RST files as well. **index.rst** file, you need to provide additional RST files as well.
As an example, consider a new manual that resides in As an example, consider a new manual that resides in **/doc/source/my-guide**.
**stx-docs/doc/source/my-guide**.
Furthermore, suppose this manual's **index.rst** file contained two Furthermore, suppose this manual's **index.rst** file contained two
links to additional complicated topics: "Topic 1" and links to additional complicated topics: "Topic 1" and
"Topic 2". "Topic 2".
The content for the new manual exists in three files: The content for the new manual exists in three files:
* stx-docs/doc/source/my-guide/index.rst** * **/doc/source/my-guide/index.rst**
* stx-docs/doc/source/my-guide/topic_1.rst** * **/doc/source/my-guide/topic_1.rst**
* stx-docs/doc/source/my-guide/topic_2.rst** * **/doc/source/my-guide/topic_2.rst**
Following shows the hierarchy: 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 The previous section described how you can provide the files
you need to create a new guide. you need to create a new guide.
This section describes how you can get the new guide to be part This section describes how to add your new guide to the table of contents in the
of the TOC StarlingX uses when displaying all the documentation documentation site.
(i.e. `StarlingX Documentation <https://docs.starlingx.io/>`_).
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. that defines the StarlingX Documentation landing page.
Inside the file, is a "Sections" area that lists the documents Inside the file, is a "Sections" area that lists the documents
that appear in the TOC. that appear in the table of contents.
Following is the updated file that shows the example guide Add your new guide to the toctree definition in the index.rst file.
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
-------------------------- --------------------------
Closing Out a Bug or Story Closing Out a Bug or Story
@@ -414,109 +262,27 @@ following command:
$ tox -e docs $ 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 ├── 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 │   └── 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 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. 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 **NOTE:** The PDF build uses a different tox environment and is
currently not supported for StarlingX. 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