From 7edaf9f52ef71e80c8d423204599cc91bb9a533c Mon Sep 17 00:00:00 2001 From: Kristal Dale Date: Wed, 28 Aug 2019 16:38:49 -0700 Subject: [PATCH] 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 --- doc/source/api-ref/index.rst | 22 +- .../contributor/doc_contribute_guide.rst | 362 ++++-------------- 2 files changed, 75 insertions(+), 309 deletions(-) diff --git a/doc/source/api-ref/index.rst b/doc/source/api-ref/index.rst index b246815e3..8af2aa368 100644 --- a/doc/source/api-ref/index.rst +++ b/doc/source/api-ref/index.rst @@ -4,17 +4,17 @@ REST API Reference StarlingX project REST API references: -* `Bare Metal `__ -* `Configuration `__ -* `Distributed Cloud `__ -* `Fault Management `__ -* `High Availability `__ -* `NFV `__ -* `Software Updates `__ +* `Bare Metal `__ +* `Configuration `__ +* `Distributed Cloud `__ +* `Fault Management `__ +* `High Availability `__ +* `NFV `__ +* `Software Updates `__ StarlingX also has API references for the modified OpenStack APIs: -* `Block Storage v2 `__ -* `Compute v2 `__ -* `Image v2 `__ -* `Network v2 `__ +* `Block Storage v2 `__ +* `Compute v2 `__ +* `Image v2 `__ +* `Network v2 `__ diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index 49573a157..f496397d4 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/doc/source/contributor/doc_contribute_guide.rst @@ -5,11 +5,8 @@ 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 +is not included in this guide. Instead refer to the `OpenStack Documentation Contributor Guide `_. --------- @@ -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 +(`_). -:: - - . - ├── 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 +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 `_. - -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. +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 `_). +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 - 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 \ No newline at end of file