diff --git a/doc/source/contributor/api_contribute_guide.rst b/doc/source/contributor/api_contribute_guide.rst index 482dc1c96..e71b20892 100644 --- a/doc/source/contributor/api_contribute_guide.rst +++ b/doc/source/contributor/api_contribute_guide.rst @@ -1,5 +1,5 @@ ===================== -API Contributor Guide +API contributor guide ===================== --------- diff --git a/doc/source/developer_guide/current/index.rst b/doc/source/contributor/build_guides/current/index.rst similarity index 96% rename from doc/source/developer_guide/current/index.rst rename to doc/source/contributor/build_guides/current/index.rst index e8d5c8e59..8ea3a7c5b 100644 --- a/doc/source/developer_guide/current/index.rst +++ b/doc/source/contributor/build_guides/current/index.rst @@ -1,12 +1,9 @@ -=========================== -Developer guide stx.2018.10 -=========================== +======================= +Build guide stx.2018.10 +======================= This section contains the steps for building a StarlingX ISO from the "current" StarlingX software (i.e. the most recently released version). -If this is not the software you want to use, see the -:doc:`available developer guides ` for -StarlingX. ------------ Requirements diff --git a/doc/source/developer_guide/latest/index.rst b/doc/source/contributor/build_guides/latest/index.rst similarity index 96% rename from doc/source/developer_guide/latest/index.rst rename to doc/source/contributor/build_guides/latest/index.rst index f3af431af..543b55a74 100644 --- a/doc/source/developer_guide/latest/index.rst +++ b/doc/source/contributor/build_guides/latest/index.rst @@ -1,12 +1,9 @@ -=========================== -Developer guide stx.2019.05 -=========================== +======================= +Build guide stx.2019.05 +======================= This section contains the steps for building a StarlingX ISO from the "latest" StarlingX software (i.e. the "under development" branch). -If this is not the software you want to use, see the -:doc:`available developer guides ` for -StarlingX. ------------ Requirements diff --git a/doc/source/contributor/development_process.rst b/doc/source/contributor/development_process.rst new file mode 100644 index 000000000..9e74a2d9c --- /dev/null +++ b/doc/source/contributor/development_process.rst @@ -0,0 +1,10 @@ +============================= +StarlingX development process +============================= + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index 3568f55f5..c3aef75ee 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/doc/source/contributor/doc_contribute_guide.rst @@ -1,5 +1,5 @@ =============================== -Documentation Contributor Guide +Documentation contributor guide =============================== This guide provides information that allows you to contribute to the diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index bc5e09cb0..1205d76b7 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -18,3 +18,40 @@ OpenStack documentation can be found in the api_contribute_guide release_note_contribute_guide doc_contribute_guide + +For information on the StarlingX development process, see the following: + +.. toctree:: + :maxdepth: 1 + + development_process + +Build guides for StarlingX are release-specific. +The following list provides help on choosing the correct +build guide based on a release: + +- The "current" release is the most recent offically released version of StarlingX. + Following is the current build guide: + + .. toctree:: + :maxdepth: 1 + + build_guides/current/index + +- The "latest" release is the forthcoming version under development. + Following is the latest build guide: + + .. toctree:: + :maxdepth: 1 + + build_guides/latest/index + +- The "archived" build guides are as follows: + + * Currently, no archived build guides exist. + + + +.. When a new release of developer guides occurs, follow the steps in the + commented block of the /installation_guide/index.rst file. + diff --git a/doc/source/contributor/release_note_contribute_guide.rst b/doc/source/contributor/release_note_contribute_guide.rst index 9a5f9ccd1..86404b47e 100644 --- a/doc/source/contributor/release_note_contribute_guide.rst +++ b/doc/source/contributor/release_note_contribute_guide.rst @@ -1,5 +1,5 @@ =============================== -Release Notes Contributor Guide +Release notes contributor guide =============================== Release notes for StarlingX projects are managed using Reno allowing release diff --git a/doc/source/installation_guide/latest/controller_storage.rst b/doc/source/deployment_guides/current/controller_storage.rst similarity index 97% rename from doc/source/installation_guide/latest/controller_storage.rst rename to doc/source/deployment_guides/current/controller_storage.rst index 1e8dc4912..5d6e5a24d 100644 --- a/doc/source/installation_guide/latest/controller_storage.rst +++ b/doc/source/deployment_guides/current/controller_storage.rst @@ -1,6 +1,6 @@ -=============================================== -Controller storage deployment guide stx.2019.05 -=============================================== +============================== +Controller storage stx.2018.10 +============================== .. contents:: :local: diff --git a/doc/source/installation_guide/current/dedicated_storage.rst b/doc/source/deployment_guides/current/dedicated_storage.rst similarity index 97% rename from doc/source/installation_guide/current/dedicated_storage.rst rename to doc/source/deployment_guides/current/dedicated_storage.rst index 73c2827e7..96ce418c7 100644 --- a/doc/source/installation_guide/current/dedicated_storage.rst +++ b/doc/source/deployment_guides/current/dedicated_storage.rst @@ -1,6 +1,6 @@ -============================================== -Dedicated storage deployment guide stx.2018.10 -============================================== +============================= +Dedicated storage stx.2018.10 +============================= .. contents:: :local: diff --git a/doc/source/installation_guide/current/deployment_terminology.rst b/doc/source/deployment_guides/current/deployment_terminology.rst similarity index 100% rename from doc/source/installation_guide/current/deployment_terminology.rst rename to doc/source/deployment_guides/current/deployment_terminology.rst diff --git a/doc/source/installation_guide/latest/duplex.rst b/doc/source/deployment_guides/current/duplex.rst similarity index 97% rename from doc/source/installation_guide/latest/duplex.rst rename to doc/source/deployment_guides/current/duplex.rst index 552aff31d..8776e44a9 100644 --- a/doc/source/installation_guide/latest/duplex.rst +++ b/doc/source/deployment_guides/current/duplex.rst @@ -1,6 +1,6 @@ -============================================== -All-In-One Duplex deployment guide stx.2019.05 -============================================== +============================= +All-in-one duplex stx.2018.10 +============================= .. contents:: :local: diff --git a/doc/source/installation_guide/current/figures/starlingx-deployment-options-controller-storage.png b/doc/source/deployment_guides/current/figures/starlingx-deployment-options-controller-storage.png similarity index 100% rename from doc/source/installation_guide/current/figures/starlingx-deployment-options-controller-storage.png rename to doc/source/deployment_guides/current/figures/starlingx-deployment-options-controller-storage.png diff --git a/doc/source/installation_guide/current/figures/starlingx-deployment-options-dedicated-storage.png b/doc/source/deployment_guides/current/figures/starlingx-deployment-options-dedicated-storage.png similarity index 100% rename from doc/source/installation_guide/current/figures/starlingx-deployment-options-dedicated-storage.png rename to doc/source/deployment_guides/current/figures/starlingx-deployment-options-dedicated-storage.png diff --git a/doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex-extended.png b/doc/source/deployment_guides/current/figures/starlingx-deployment-options-duplex-extended.png similarity index 100% rename from doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex-extended.png rename to doc/source/deployment_guides/current/figures/starlingx-deployment-options-duplex-extended.png diff --git a/doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex.png b/doc/source/deployment_guides/current/figures/starlingx-deployment-options-duplex.png similarity index 100% rename from doc/source/installation_guide/current/figures/starlingx-deployment-options-duplex.png rename to doc/source/deployment_guides/current/figures/starlingx-deployment-options-duplex.png diff --git a/doc/source/installation_guide/current/figures/starlingx-deployment-options-simplex.png b/doc/source/deployment_guides/current/figures/starlingx-deployment-options-simplex.png similarity index 100% rename from doc/source/installation_guide/current/figures/starlingx-deployment-options-simplex.png rename to doc/source/deployment_guides/current/figures/starlingx-deployment-options-simplex.png diff --git a/doc/source/installation_guide/latest/simplex.rst b/doc/source/deployment_guides/current/simplex.rst similarity index 97% rename from doc/source/installation_guide/latest/simplex.rst rename to doc/source/deployment_guides/current/simplex.rst index d3ea0c826..fdff6a46b 100644 --- a/doc/source/installation_guide/latest/simplex.rst +++ b/doc/source/deployment_guides/current/simplex.rst @@ -1,6 +1,6 @@ -=============================================== -All-In-One Simplex deployment guide stx.2019.05 -=============================================== +============================== +All-in-one simplex stx.2018.10 +============================== .. contents:: :local: diff --git a/doc/source/deployment_guides/index.rst b/doc/source/deployment_guides/index.rst new file mode 100644 index 000000000..3cab22b23 --- /dev/null +++ b/doc/source/deployment_guides/index.rst @@ -0,0 +1,95 @@ +================= +Deployment Guides +================= + +Deployment guides for StarlingX are release-specific. +The following list provides help on choosing the correct deployment guide: + +- The "current" release is the most recent offically released version of StarlingX. + Following are the current deployment guides: + + .. toctree:: + :maxdepth: 1 + + ../deployment_guides/current/simplex + ../deployment_guides/current/duplex + ../deployment_guides/current/controller_storage + ../deployment_guides/current/dedicated_storage + +- The "latest" release is the forthcoming version under development. + Following are the latest deployment guides: + + .. toctree:: + :maxdepth: 1 + + latest/planning/index + latest/options/index + latest/aio_simplex/index + latest/aio_duplex/index + latest/aio_duplex_computes/index + latest/controller_storage/index + latest/dedicated_storage/index + latest/ironic/index + latest/multi_region/index + latest/dist_cloud/index + +- Following are deployment guides for past StartlingX releases that have + been archived: + + * Currently, no archived deployment guides exist. + + +.. Steps you must take when a new release of the installer and developer guides occurs: + +.. 1. Archive the "current" release: + 1. Rename the "current" folder to the release name using the convention (e.g. 2018_10). + 2. Get inside your new folder (i.e. the old "current" folder) and update all links in the *.rst + files to use the new path (e.g. :doc:`Libvirt/QEMU ` + becomes + :doc:`Libvirt/QEMU /installation_libvirt_qemu>` + 3. You might want to change your working directory to / and use Git to grep for + the "current" string (i.e. 'git grep "current" *'). For each applicable occurence, make + the call whether or not to convert the string to the actual archived string "". + Be sure to scrub all files for the "current" string in both the "installation_guide" + and "developer_guide" folders downward. + 2. Add the new "current" release: + 1. Rename the existing "latest" folders to "current". This assumes that "latest" represented + the under-development release that just officially released. + 2. Get inside your new folder (i.e. the old "latest" folder) and update all links in the *.rst + files to use the new path (e.g. :doc:`Libvirt/QEMU ` + becomes + :doc:`Libvirt/QEMU ` + 3. You might want to change your working directory to the "current" directory and use Git to grep for + the "latest" string (i.e. 'git grep "latest" *'). For each applicable occurence, make + the call whether or not to convert the string to "current". + Be sure to scrub all files for the "latest" string in both the "installation_guide" + and "developer_guide" folders downward. + 4. Because the "current" release is now available, make sure to update these pages: + - index + - installation guide + - developer guide + - release notes + 3. Create a new "latest" release, which are the installation and developer guides under development: + 1. Copy your "current" folders and rename them "latest". + 2. Make sure the new files have the correct version in the page title and intro + sentence (e.g. '2019.10.rc1 Installation Guide'). + 3. Make sure all files in new "latest" link to the correct versions of supporting + docs. You do this through the doc link, so that it resolves to the top of the page + (e.g. :doc:`/installation_guide/latest/index`) + 4. Make sure the new release index is labeled with the correct version name + (e.g .. _index-2019-05:) + 5. Add the archived version to the toctree on this page. You want all possible versions + to build. + 6. Since you are adding a new version ("latest") *before* it is available + (e.g. to begin work on new docs), make sure page text still directs user to the + "current" release and not to the under development version of the manuals. + + + + + + + + + + diff --git a/doc/source/installation_guide/current/duplex.rst b/doc/source/deployment_guides/latest/aio_duplex/index.rst similarity index 97% rename from doc/source/installation_guide/current/duplex.rst rename to doc/source/deployment_guides/latest/aio_duplex/index.rst index 0eb427cb1..5721385eb 100644 --- a/doc/source/installation_guide/current/duplex.rst +++ b/doc/source/deployment_guides/latest/aio_duplex/index.rst @@ -1,6 +1,6 @@ -============================================== -All-In-One Duplex deployment guide stx.2018.10 -============================================== +============================= +All-in-one duplex stx.2019.05 +============================= .. contents:: :local: @@ -31,7 +31,7 @@ consolidated onto a protected pair of physical servers. For example: or different distributions of operating systems by using multiple virtual machines. -.. figure:: figures/starlingx-deployment-options-duplex.png +.. figure:: ../figures/starlingx-deployment-options-duplex.png :scale: 50% :alt: All-In-One Duplex deployment configuration @@ -70,7 +70,7 @@ someone starting with an All-In-One Duplex deployment. With this option, virtual machines can be scheduled on either of the all-in-one controller nodes and/or the compute nodes. -.. figure:: figures/starlingx-deployment-options-duplex-extended.png +.. figure:: ../figures/starlingx-deployment-options-duplex-extended.png :scale: 50% :alt: All-In-One Duplex Extended Deployment Configuration @@ -1507,14 +1507,14 @@ machines. Deployment terminology ---------------------- -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-simplex-deployment-terminology: :end-before: incl-simplex-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-standard-controller-deployment-terminology: :end-before: incl-standard-controller-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-common-deployment-terminology: :end-before: incl-common-deployment-terminology-end: diff --git a/doc/source/deployment_guides/latest/aio_duplex_computes/index.rst b/doc/source/deployment_guides/latest/aio_duplex_computes/index.rst new file mode 100644 index 000000000..068aed276 --- /dev/null +++ b/doc/source/deployment_guides/latest/aio_duplex_computes/index.rst @@ -0,0 +1,10 @@ +========================================== +All-in-one duplex with up to four computes +========================================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/installation_guide/current/simplex.rst b/doc/source/deployment_guides/latest/aio_simplex/index.rst similarity index 96% rename from doc/source/installation_guide/current/simplex.rst rename to doc/source/deployment_guides/latest/aio_simplex/index.rst index c639cba32..b604af7b2 100644 --- a/doc/source/installation_guide/current/simplex.rst +++ b/doc/source/deployment_guides/latest/aio_simplex/index.rst @@ -1,6 +1,6 @@ -=============================================== -All-In-One Simplex deployment guide stx.2018.10 -=============================================== +============================== +All-in-one simplex stx.2019.05 +============================== .. contents:: :local: @@ -31,7 +31,7 @@ deployment you can: Only a small amount of cloud processing / storage power is required with an All-In-One Simplex deployment. -.. figure:: figures/starlingx-deployment-options-simplex.png +.. figure:: ../figures/starlingx-deployment-options-simplex.png :scale: 50% :alt: All-In-One Simplex deployment configuration @@ -716,14 +716,14 @@ Nova Flavors, configure Neutron networks and launch Nova virtual machines. Deployment terminology ---------------------- -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-simplex-deployment-terminology: :end-before: incl-simplex-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-standard-controller-deployment-terminology: :end-before: incl-standard-controller-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-common-deployment-terminology: :end-before: incl-common-deployment-terminology-end: diff --git a/doc/source/installation_guide/current/controller_storage.rst b/doc/source/deployment_guides/latest/controller_storage/index.rst similarity index 97% rename from doc/source/installation_guide/current/controller_storage.rst rename to doc/source/deployment_guides/latest/controller_storage/index.rst index 263e8f27a..c06f47a71 100644 --- a/doc/source/installation_guide/current/controller_storage.rst +++ b/doc/source/deployment_guides/latest/controller_storage/index.rst @@ -1,6 +1,6 @@ -=============================================== -Controller storage deployment guide stx.2018.10 -=============================================== +============================== +Controller storage stx.2019.05 +============================== .. contents:: :local: @@ -28,7 +28,7 @@ controller / storage cluster with: - Storage function running on top of LVM on single second disk, DRBD-sync'd between the controller nodes. -.. figure:: figures/starlingx-deployment-options-controller-storage.png +.. figure:: ../figures/starlingx-deployment-options-controller-storage.png :scale: 50% :alt: Controller Storage deployment configuration @@ -965,10 +965,10 @@ virtual machines. Deployment terminology ---------------------- -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-standard-controller-deployment-terminology: :end-before: incl-standard-controller-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-common-deployment-terminology: :end-before: incl-common-deployment-terminology-end: diff --git a/doc/source/installation_guide/latest/dedicated_storage.rst b/doc/source/deployment_guides/latest/dedicated_storage/index.rst similarity index 96% rename from doc/source/installation_guide/latest/dedicated_storage.rst rename to doc/source/deployment_guides/latest/dedicated_storage/index.rst index 42efea424..4ebe1eb49 100644 --- a/doc/source/installation_guide/latest/dedicated_storage.rst +++ b/doc/source/deployment_guides/latest/dedicated_storage/index.rst @@ -1,6 +1,6 @@ -============================================== -Dedicated storage deployment guide stx.2019.05 -============================================== +============================= +Dedicated storage stx.2019.05 +============================= .. contents:: :local: @@ -23,7 +23,7 @@ This deployment option provides the maximum capacity for a single region deployment, with a supported growth path to a multi-region deployment option by adding a secondary region. -.. figure:: figures/starlingx-deployment-options-dedicated-storage.png +.. figure:: ../figures/starlingx-deployment-options-dedicated-storage.png :scale: 50% :alt: Dedicated Storage deployment configuration @@ -905,14 +905,14 @@ launch Nova virtual machines. Deployment terminology ---------------------- -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-standard-controller-deployment-terminology: :end-before: incl-standard-controller-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-dedicated-storage-deployment-terminology: :end-before: incl-dedicated-storage-deployment-terminology-end: -.. include:: deployment_terminology.rst +.. include:: ../deployment_terminology.rst :start-after: incl-common-deployment-terminology: :end-before: incl-common-deployment-terminology-end: diff --git a/doc/source/installation_guide/latest/deployment_terminology.rst b/doc/source/deployment_guides/latest/deployment_terminology.rst similarity index 100% rename from doc/source/installation_guide/latest/deployment_terminology.rst rename to doc/source/deployment_guides/latest/deployment_terminology.rst diff --git a/doc/source/deployment_guides/latest/dist_cloud/index.rst b/doc/source/deployment_guides/latest/dist_cloud/index.rst new file mode 100644 index 000000000..d41bfc3ea --- /dev/null +++ b/doc/source/deployment_guides/latest/dist_cloud/index.rst @@ -0,0 +1,10 @@ +================= +Distributed cloud +================= + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-controller-storage.png b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-controller-storage.png new file mode 100644 index 000000000..c1d028acf Binary files /dev/null and b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-controller-storage.png differ diff --git a/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-dedicated-storage.png b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-dedicated-storage.png new file mode 100644 index 000000000..00e4c3eba Binary files /dev/null and b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-dedicated-storage.png differ diff --git a/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-duplex-extended.png b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-duplex-extended.png new file mode 100644 index 000000000..64bb7f5ab Binary files /dev/null and b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-duplex-extended.png differ diff --git a/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-duplex.png b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-duplex.png new file mode 100644 index 000000000..3638e4a10 Binary files /dev/null and b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-duplex.png differ diff --git a/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-simplex.png b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-simplex.png new file mode 100644 index 000000000..317b7cf49 Binary files /dev/null and b/doc/source/deployment_guides/latest/figures/starlingx-deployment-options-simplex.png differ diff --git a/doc/source/deployment_guides/latest/ironic/index.rst b/doc/source/deployment_guides/latest/ironic/index.rst new file mode 100644 index 000000000..58ad7b74c --- /dev/null +++ b/doc/source/deployment_guides/latest/ironic/index.rst @@ -0,0 +1,10 @@ +==================== +Standard with Ironic +==================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/deployment_guides/latest/multi_region/index.rst b/doc/source/deployment_guides/latest/multi_region/index.rst new file mode 100644 index 000000000..b3564eebd --- /dev/null +++ b/doc/source/deployment_guides/latest/multi_region/index.rst @@ -0,0 +1,10 @@ +============ +Multi-region +============ + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/deployment_guides/latest/options/index.rst b/doc/source/deployment_guides/latest/options/index.rst new file mode 100644 index 000000000..9b224402e --- /dev/null +++ b/doc/source/deployment_guides/latest/options/index.rst @@ -0,0 +1,10 @@ +================== +Deployment options +================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/deployment_guides/latest/planning/index.rst b/doc/source/deployment_guides/latest/planning/index.rst new file mode 100644 index 000000000..eba8e0adf --- /dev/null +++ b/doc/source/deployment_guides/latest/planning/index.rst @@ -0,0 +1,10 @@ +=================== +Deployment planning +=================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/developer_guide/index.rst b/doc/source/developer_guide/index.rst deleted file mode 100644 index 3e2012a7f..000000000 --- a/doc/source/developer_guide/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -================ -Developer guides -================ - -Developer guides for StarlingX are release-specific. -The following list provides help on choosing the correct -developer guide based on a release: - -- The "current" release is the most recent offically released version of StarlingX. - To build a StarlingX ISO from the current release, use the :doc:`/developer_guide/current/index`. - -- The "latest" release is the forthcoming version under development. - To build a StarlingX ISO using the latest release, use the :doc:`/developer_guide/latest/index`. - -- Following are all available developer guides for StarlingX: - - .. toctree:: - :maxdepth: 1 - - /developer_guide/current/index - /developer_guide/latest/index - -.. When a new release of developer guides occurs, follow the steps in the - commented block of the /installation_guide/index.rst file. - diff --git a/doc/source/developer_resources/architecture_docs.rst b/doc/source/developer_resources/architecture_docs.rst new file mode 100644 index 000000000..ecd4ecb39 --- /dev/null +++ b/doc/source/developer_resources/architecture_docs.rst @@ -0,0 +1,10 @@ +================================ +StarlingX architecture documents +================================ + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/developer_resources/index.rst b/doc/source/developer_resources/index.rst new file mode 100644 index 000000000..8ab146812 --- /dev/null +++ b/doc/source/developer_resources/index.rst @@ -0,0 +1,21 @@ +.. _developer_resources: + +=================== +Developer Resources +=================== + +StarlingX developer resources exist that help you understand the +architecture of the documentation, how to navigate the StarlingX +source code, and understand the development process. + +The developer guide is release-specific. +The following list provides help on choosing the correct +developer guide based on a release: + +.. toctree:: + :maxdepth: 1 + + navigate_source_code + architecture_docs + Project Specifications + diff --git a/doc/source/developer_resources/navigate_source_code.rst b/doc/source/developer_resources/navigate_source_code.rst new file mode 100644 index 000000000..7a14dfe75 --- /dev/null +++ b/doc/source/developer_resources/navigate_source_code.rst @@ -0,0 +1,10 @@ +========================================= +How to navigate the StarlingX source code +========================================= + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/index.rst b/doc/source/index.rst index 2ff5cdb34..3d8faaf47 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,12 +16,13 @@ Sections .. toctree:: :maxdepth: 1 + introduction/index + deployment_guides/index installation_guide/index - developer_guide/index - Project Specifications - api-ref/index - releasenotes/index + operation_guides/index contributor/index + releasenotes/index + developer_resources/index -------- Projects diff --git a/doc/source/installation_guide/current/index.rst b/doc/source/installation_guide/current/index.rst index 6417c1cc6..92670e338 100644 --- a/doc/source/installation_guide/current/index.rst +++ b/doc/source/installation_guide/current/index.rst @@ -243,7 +243,7 @@ Unload firewall and disable firewall on boot: Getting the StarlingX ISO image ------------------------------- -Follow the instructions from the :doc:`/developer_guide/current/index` to build a +Follow the instructions from the :doc:`/contributor/build_guides/current/index` to build a StarlingX ISO image. ********** @@ -271,19 +271,16 @@ Deployment options - Standard controller - - :doc:`StarlingX Cloud with Dedicated Storage ` - - :doc:`StarlingX Cloud with Controller Storage ` + - :doc:`StarlingX Cloud with Dedicated Storage ` + - :doc:`StarlingX Cloud with Controller Storage ` - All-in-one - - :doc:`StarlingX Cloud Duplex ` - - :doc:`StarlingX Cloud Simplex ` + - :doc:`StarlingX Cloud Duplex ` + - :doc:`StarlingX Cloud Simplex ` .. toctree:: :hidden: installation_libvirt_qemu - controller_storage - dedicated_storage - duplex - simplex + diff --git a/doc/source/installation_guide/current/installation_libvirt_qemu.rst b/doc/source/installation_guide/current/installation_libvirt_qemu.rst index f045a8c21..f68d8bea8 100644 --- a/doc/source/installation_guide/current/installation_libvirt_qemu.rst +++ b/doc/source/installation_guide/current/installation_libvirt_qemu.rst @@ -195,10 +195,10 @@ controller-0 step. - Standard controller - - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment ` - - :doc:`StarlingX Cloud with Controller Storage Virtual Environment ` + - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment ` + - :doc:`StarlingX Cloud with Controller Storage Virtual Environment ` - All-in-one - - :doc:`StarlingX Cloud Duplex Virtual Environment ` - - :doc:`StarlingX Cloud Simplex Virtual Environment ` + - :doc:`StarlingX Cloud Duplex Virtual Environment ` + - :doc:`StarlingX Cloud Simplex Virtual Environment ` diff --git a/doc/source/installation_guide/index.rst b/doc/source/installation_guide/index.rst index 7b7382d77..7971403ca 100644 --- a/doc/source/installation_guide/index.rst +++ b/doc/source/installation_guide/index.rst @@ -1,24 +1,31 @@ =================== -Installation guides +Installation Guides =================== Installation steps for StarlingX are release-specific. The following list provides help on choosing the correct installation steps: -- The "current" release is the most recent offically released version of StarlingX. - To install the current release of StarlingX, use the :doc:`/installation_guide/current/index`. - -- The "latest" release is the forthcoming version under development. - To install the latest release of StarlingX, use the :doc:`/installation_guide/latest/index`. - -- Following are all available installation steps for StarlingX: +- The "current" release is the most recent offically released version of StarlingX: .. toctree:: :maxdepth: 1 /installation_guide/current/index + +- The "latest" release is the forthcoming version under development: + + .. toctree:: + :maxdepth: 1 + /installation_guide/latest/index +- The "archived" installation documents are as follows: + + * Currently, no archived installation documents exist. + + + + .. Steps you must take when a new release of the installer and developer guides occurs: @@ -67,3 +74,7 @@ The following list provides help on choosing the correct installation steps: + + + + diff --git a/doc/source/installation_guide/latest/additional_os_services.rst b/doc/source/installation_guide/latest/additional_os_services.rst new file mode 100644 index 000000000..4ccd8e955 --- /dev/null +++ b/doc/source/installation_guide/latest/additional_os_services.rst @@ -0,0 +1,10 @@ +================================================ +Additional OpenStack Services Installation Guide +================================================ + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/installation_guide/latest/aio_duplex_computes.rst b/doc/source/installation_guide/latest/aio_duplex_computes.rst new file mode 100644 index 000000000..858915f0f --- /dev/null +++ b/doc/source/installation_guide/latest/aio_duplex_computes.rst @@ -0,0 +1,10 @@ +================================================== +All-in-one Duplex with Computes Installation Guide +================================================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/installation_guide/latest/dist_cloud.rst b/doc/source/installation_guide/latest/dist_cloud.rst new file mode 100644 index 000000000..011994952 --- /dev/null +++ b/doc/source/installation_guide/latest/dist_cloud.rst @@ -0,0 +1,10 @@ +==================================== +Distributed Cloud Installation Guide +==================================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/installation_guide/latest/index.rst b/doc/source/installation_guide/latest/index.rst index 25c3fa3c0..0af92f918 100644 --- a/doc/source/installation_guide/latest/index.rst +++ b/doc/source/installation_guide/latest/index.rst @@ -2,10 +2,9 @@ Installation guide stx.2019.05 ============================== -This is the installation guide for the "latest" StarlingX software -(i.e. the "under development" branch). -If this is not the the installation guide you want to use, -see the +This is the installation guide for the "current" StarlingX software +(i.e. the most recently released version). +If this is not the installation guide you want to use, see the :doc:`available installation guides `. ------------ @@ -244,7 +243,7 @@ Unload firewall and disable firewall on boot: Getting the StarlingX ISO image ------------------------------- -Follow the instructions from the :doc:`/developer_guide/latest/index` to build a +Follow the instructions from the :doc:`/contributor/build_guides/latest/index` to build a StarlingX ISO image. ********** @@ -265,26 +264,34 @@ directory: $ cp $HOME/stx-tools/deployment/libvirt/ +.. toctree:: + :hidden: + + aio_duplex_computes + additional_os_services + multi_region + dist_cloud + installation_libvirt_qemu ------------------ Deployment options ------------------ -- Standard controller - - - :doc:`StarlingX Cloud with Dedicated Storage ` - - :doc:`StarlingX Cloud with Controller Storage ` - - All-in-one - - :doc:`StarlingX Cloud Duplex ` - - :doc:`StarlingX Cloud Simplex ` + - :doc:`StarlingX Cloud Simplex ` + - :doc:`StarlingX Cloud Duplex ` + - :doc:`StarlingX Cloud Duplex with Computes ` + +- Standard controller + + - :doc:`StarlingX Cloud with Controller Storage ` + - :doc:`StarlingX Cloud with Dedicated Storage ` + +- Others + + - :doc:`Multi-region ` + - :doc:`Distributed cloud ` + - :doc:`Additional OpenStack services ` -.. toctree:: - :hidden: - installation_libvirt_qemu - controller_storage - dedicated_storage - duplex - simplex diff --git a/doc/source/installation_guide/latest/installation_libvirt_qemu.rst b/doc/source/installation_guide/latest/installation_libvirt_qemu.rst index 84e02c3b9..7722007a4 100644 --- a/doc/source/installation_guide/latest/installation_libvirt_qemu.rst +++ b/doc/source/installation_guide/latest/installation_libvirt_qemu.rst @@ -195,10 +195,10 @@ controller-0 step. - Standard controller - - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment ` - - :doc:`StarlingX Cloud with Controller Storage Virtual Environment ` + - :doc:`StarlingX Cloud with Dedicated Storage Virtual Environment ` + - :doc:`StarlingX Cloud with Controller Storage Virtual Environment ` - All-in-one - - :doc:`StarlingX Cloud Duplex Virtual Environment ` - - :doc:`StarlingX Cloud Simplex Virtual Environment ` + - :doc:`StarlingX Cloud Duplex Virtual Environment ` + - :doc:`StarlingX Cloud Simplex Virtual Environment ` diff --git a/doc/source/installation_guide/latest/multi_region.rst b/doc/source/installation_guide/latest/multi_region.rst new file mode 100644 index 000000000..7c1136bcc --- /dev/null +++ b/doc/source/installation_guide/latest/multi_region.rst @@ -0,0 +1,10 @@ +=============================== +Multi-Region Installation Guide +=============================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/introduction/box.rst b/doc/source/introduction/box.rst new file mode 100644 index 000000000..7def184f4 --- /dev/null +++ b/doc/source/introduction/box.rst @@ -0,0 +1,10 @@ +================== +StarlingX in a box +================== + +This topic is coming soon. + +.. Linked Story does not yet exist. + +`Linked Story `__ + diff --git a/doc/source/introduction/index.rst b/doc/source/introduction/index.rst new file mode 100644 index 000000000..a8a411cfd --- /dev/null +++ b/doc/source/introduction/index.rst @@ -0,0 +1,26 @@ +====================== +StarlingX Introduction +====================== + +StarlingX encompasses many areas. +The information in this section introduces you to StarlingX, +describes how various users use StarlingX, how StarlingX +behaves "out of the box", how software evaluation occurs, and +a roadmap of the documentation. + +Following are the introductory topics available for StarlingX: + +.. toctree:: + :maxdepth: 1 + + /introduction/intro + /introduction/kubernetes + /introduction/openstack + /introduction/box + /introduction/software_evaluation + /introduction/roadmap + + + + + diff --git a/doc/source/introduction/intro.rst b/doc/source/introduction/intro.rst new file mode 100644 index 000000000..86692453f --- /dev/null +++ b/doc/source/introduction/intro.rst @@ -0,0 +1,8 @@ +==================== +Project introduction +==================== + +This topic is coming soon. + +`Linked Story `__ + diff --git a/doc/source/introduction/kubernetes.rst b/doc/source/introduction/kubernetes.rst new file mode 100644 index 000000000..1e576e575 --- /dev/null +++ b/doc/source/introduction/kubernetes.rst @@ -0,0 +1,10 @@ +================ +Kubernetes users +================ + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/introduction/openstack.rst b/doc/source/introduction/openstack.rst new file mode 100644 index 000000000..4bcbdf395 --- /dev/null +++ b/doc/source/introduction/openstack.rst @@ -0,0 +1,10 @@ +=============== +OpenStack users +=============== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/introduction/roadmap.rst b/doc/source/introduction/roadmap.rst new file mode 100644 index 000000000..f7bec2bd6 --- /dev/null +++ b/doc/source/introduction/roadmap.rst @@ -0,0 +1,10 @@ +===================== +Documentation roadmap +===================== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/introduction/software_evaluation.rst b/doc/source/introduction/software_evaluation.rst new file mode 100644 index 000000000..56f5161be --- /dev/null +++ b/doc/source/introduction/software_evaluation.rst @@ -0,0 +1,10 @@ +========================= +Software evaluation guide +========================= + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/index.rst b/doc/source/operation_guides/index.rst new file mode 100644 index 000000000..ca0cadb33 --- /dev/null +++ b/doc/source/operation_guides/index.rst @@ -0,0 +1,92 @@ +================ +Operation Guides +================ + +Operation guides for StarlingX are release-specific. +The following list provides help on choosing the correct operations guide: + +- The "current" release is the most recent offically released version of StarlingX. + Following are the current operation guides: + + .. toctree:: + :maxdepth: 1 + + ../api-ref/index + +- The "latest" release is the forthcoming version under development. + Following are the latest operation guides: + + .. toctree:: + :maxdepth: 1 + + ../api-ref/index + latest/cli_reference/index + latest/data_network_config/index + latest/ceph_storage_config/index + latest/sdn_networking/index + latest/kubernetes_cluster_guide/index + latest/swift_config_management/index + latest/fault_management/index + latest/patching_guide/index + latest/upgrade_guide/index + +- Following are operation guides for past StartlingX releases that have + been archived: + + * Currently, no archived operation guides exist. + + +.. Steps you must take when a new release of the installer and developer guides occurs: + +.. 1. Archive the "current" release: + 1. Rename the "current" folder to the release name using the convention (e.g. 2018_10). + 2. Get inside your new folder (i.e. the old "current" folder) and update all links in the *.rst + files to use the new path (e.g. :doc:`Libvirt/QEMU ` + becomes + :doc:`Libvirt/QEMU /installation_libvirt_qemu>` + 3. You might want to change your working directory to / and use Git to grep for + the "current" string (i.e. 'git grep "current" *'). For each applicable occurence, make + the call whether or not to convert the string to the actual archived string "". + Be sure to scrub all files for the "current" string in both the "installation_guide" + and "developer_guide" folders downward. + 2. Add the new "current" release: + 1. Rename the existing "latest" folders to "current". This assumes that "latest" represented + the under-development release that just officially released. + 2. Get inside your new folder (i.e. the old "latest" folder) and update all links in the *.rst + files to use the new path (e.g. :doc:`Libvirt/QEMU ` + becomes + :doc:`Libvirt/QEMU ` + 3. You might want to change your working directory to the "current" directory and use Git to grep for + the "latest" string (i.e. 'git grep "latest" *'). For each applicable occurence, make + the call whether or not to convert the string to "current". + Be sure to scrub all files for the "latest" string in both the "installation_guide" + and "developer_guide" folders downward. + 4. Because the "current" release is now available, make sure to update these pages: + - index + - installation guide + - developer guide + - release notes + 3. Create a new "latest" release, which are the installation and developer guides under development: + 1. Copy your "current" folders and rename them "latest". + 2. Make sure the new files have the correct version in the page title and intro + sentence (e.g. '2019.10.rc1 Installation Guide'). + 3. Make sure all files in new "latest" link to the correct versions of supporting + docs. You do this through the doc link, so that it resolves to the top of the page + (e.g. :doc:`/installation_guide/latest/index`) + 4. Make sure the new release index is labeled with the correct version name + (e.g .. _index-2019-05:) + 5. Add the archived version to the toctree on this page. You want all possible versions + to build. + 6. Since you are adding a new version ("latest") *before* it is available + (e.g. to begin work on new docs), make sure page text still directs user to the + "current" release and not to the under development version of the manuals. + + + + + + + + + + diff --git a/doc/source/operation_guides/latest/ceph_storage_config/index.rst b/doc/source/operation_guides/latest/ceph_storage_config/index.rst new file mode 100644 index 000000000..8dff42d54 --- /dev/null +++ b/doc/source/operation_guides/latest/ceph_storage_config/index.rst @@ -0,0 +1,10 @@ +========================== +CEPH storage configuration +========================== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/cli_reference/index.rst b/doc/source/operation_guides/latest/cli_reference/index.rst new file mode 100644 index 000000000..c99f28e30 --- /dev/null +++ b/doc/source/operation_guides/latest/cli_reference/index.rst @@ -0,0 +1,10 @@ +============= +CLI reference +============= + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/data_network_config/index.rst b/doc/source/operation_guides/latest/data_network_config/index.rst new file mode 100644 index 000000000..626385602 --- /dev/null +++ b/doc/source/operation_guides/latest/data_network_config/index.rst @@ -0,0 +1,10 @@ +========================== +Data network configuration +========================== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/fault_management/index.rst b/doc/source/operation_guides/latest/fault_management/index.rst new file mode 100644 index 000000000..8566f4241 --- /dev/null +++ b/doc/source/operation_guides/latest/fault_management/index.rst @@ -0,0 +1,10 @@ +================ +Fault management +================ + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/kubernetes_cluster_guide/index.rst b/doc/source/operation_guides/latest/kubernetes_cluster_guide/index.rst new file mode 100644 index 000000000..4b7e5c837 --- /dev/null +++ b/doc/source/operation_guides/latest/kubernetes_cluster_guide/index.rst @@ -0,0 +1,10 @@ +================== +Kubernetes cluster +================== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/patching_guide/index.rst b/doc/source/operation_guides/latest/patching_guide/index.rst new file mode 100644 index 000000000..96c003eda --- /dev/null +++ b/doc/source/operation_guides/latest/patching_guide/index.rst @@ -0,0 +1,10 @@ +======== +Patching +======== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/sdn_networking/index.rst b/doc/source/operation_guides/latest/sdn_networking/index.rst new file mode 100644 index 000000000..683384df3 --- /dev/null +++ b/doc/source/operation_guides/latest/sdn_networking/index.rst @@ -0,0 +1,10 @@ +============== +SDN networking +============== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/swift_config_management/index.rst b/doc/source/operation_guides/latest/swift_config_management/index.rst new file mode 100644 index 000000000..6b711185a --- /dev/null +++ b/doc/source/operation_guides/latest/swift_config_management/index.rst @@ -0,0 +1,10 @@ +================================== +SWIFT configuration and management +================================== + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ + diff --git a/doc/source/operation_guides/latest/upgrade_guide/index.rst b/doc/source/operation_guides/latest/upgrade_guide/index.rst new file mode 100644 index 000000000..dfce0b496 --- /dev/null +++ b/doc/source/operation_guides/latest/upgrade_guide/index.rst @@ -0,0 +1,10 @@ +======= +Upgrade +======= + +This topic is coming soon. + +Linked Story does not yet exist. + +.. `Linked Story `__ +