From 0019c23725757e4600bff496344dd15bbd7c4100 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 3 Dec 2018 11:38:30 -0800 Subject: [PATCH] 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 --- .../contributor/doc_contribute_guide.rst | 445 ++++++++++++++++++ doc/source/contributor/index.rst | 4 +- 2 files changed, 448 insertions(+), 1 deletion(-) create mode 100644 doc/source/contributor/doc_contribute_guide.rst diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst new file mode 100644 index 000000000..7df958b7e --- /dev/null +++ b/doc/source/contributor/doc_contribute_guide.rst @@ -0,0 +1,445 @@ +=============================== +Documentation Contributor Guide +=============================== + +This guide provides information that allows you to contribute to the +`StarlingX documentation `_. + +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 `_. + +--------- +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 (`_). + +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 `_. + +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 `_. +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 ` + - :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 you can get the new guide to be part +of the TOC StarlingX uses when displaying all the documentation +(i.e. `StarlingX Documentation `_). + +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 + 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. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 1891640a1..bc5e09cb0 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -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 `_. .. _`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