Documentation Contributor Guide: First draft of new StarlingX guide
I have created the initial draft of a new StarlingX guide called "Documentation Contributor Guide". The guide lives alongside the existing StarlingX contributor guides. This involved an update to the contributor folder's "index.rst" file and a new content file named stx-docs/doc/source/doc_contribute_guide.rst". Change-Id: I54adedb520869bed462dfee30098404a09dfca8e Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
This commit is contained in:
Scott Rifenbark
parent
0644cfb828
commit
0019c23725
|
|
@ -0,0 +1,445 @@
|
|||
===============================
|
||||
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
|
||||
`OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
|
||||
|
||||
---------
|
||||
Locations
|
||||
---------
|
||||
|
||||
StarlingX documentation consists of several types of manuals and is found
|
||||
in the **stx-docs** and **stx-specs** projects (i.e. repositories).
|
||||
These projects contain hierarchy that organizes the documentation by topic:
|
||||
|
||||
- **Installation Guide**
|
||||
|
||||
- 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**
|
||||
|
||||
- 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**
|
||||
|
||||
- Describes specifications, specification templates, and processes
|
||||
for submitting a specification.
|
||||
This guide is located in **stx-specs/doc/source**.
|
||||
- **REST API Reference**
|
||||
|
||||
- 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**
|
||||
|
||||
- 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**.
|
||||
|
||||
--------------------
|
||||
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.
|
||||
|
||||
Following is the structure of the **stx-docs** repository:
|
||||
|
||||
::
|
||||
|
||||
.
|
||||
├── 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
|
||||
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.
|
||||
The actual landing page (content) for the API Reference documents
|
||||
is in the **stx-docs/doc/source/api-ref/index.rst** file.
|
||||
|
||||
Here is the structure of the **stx-specs** project:
|
||||
|
||||
::
|
||||
|
||||
.
|
||||
├── 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.
|
||||
|
||||
-----------------
|
||||
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.
|
||||
|
||||
-----------------
|
||||
Creating a Manual
|
||||
-----------------
|
||||
|
||||
Creating a new manual for **stx-docs** involves minimally providing the
|
||||
**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**.
|
||||
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**
|
||||
|
||||
Following shows the hierarchy:
|
||||
|
||||
::
|
||||
|
||||
├── doc
|
||||
│ └── source
|
||||
│ ├── my_guide
|
||||
│ │ ├── index.rst
|
||||
│ │ ├── topic_1.rst
|
||||
│ │ ├── topic_2.rst
|
||||
|
||||
|
||||
-----------------------
|
||||
Creating the Index File
|
||||
-----------------------
|
||||
|
||||
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.
|
||||
|
||||
The syntax of the **index.rst** file is fixed. Following shows the
|
||||
sample **index.rst** file for the new guide:
|
||||
|
||||
::
|
||||
|
||||
========
|
||||
My Guide
|
||||
========
|
||||
|
||||
The new guide.
|
||||
|
||||
- :ref:`Topic 1 <topic_1>`
|
||||
- :ref:`Topic 2 <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 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/>`_).
|
||||
|
||||
The **stx-docs/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
|
||||
|
||||
--------------------------
|
||||
Building the Documentation
|
||||
--------------------------
|
||||
|
||||
To build the documentation locally in HTML format, use the
|
||||
following command:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
$ tox -e docs
|
||||
|
||||
The resulting directories and HTML files looks like:
|
||||
|
||||
::
|
||||
|
||||
stx-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
|
||||
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.
|
||||
|
|
@ -7,7 +7,8 @@ Contribute
|
|||
Please use the following guides when contributing to the StarlingX
|
||||
documentation. Additional information about contributing to
|
||||
OpenStack documentation can be found in the
|
||||
`OpenStack API documentation guide`_.
|
||||
`OpenStack API documentation guide`_ and the
|
||||
`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
|
||||
|
||||
|
|
@ -16,3 +17,4 @@ OpenStack documentation can be found in the
|
|||
|
||||
api_contribute_guide
|
||||
release_note_contribute_guide
|
||||
doc_contribute_guide
|
||||
|
|
|
|||
Loading…
Reference in New Issue