starlingx
/
docs
Code Issues Proposed changes

Updates to HTML theme completed 

Updated conf.py to enable "show_other_versions"

Made clerical edits to test new theme output

Change-Id: I7637a18204004383220ae723cb42eb94e4d5bebd
Signed-off-by: MCamp859 <maryx.camp@intel.com>
This commit is contained in:
MCamp859 2020-07-06 21:46:20 -04:00
parent 43f51bcaea
commit 965e7aebe6
2 changed files with 41 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/conf.py
View File

@ -82,7 +82,11 @@ html_theme = 'starlingxdocs'
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
# documentation. # documentation.
# #
# html_theme_options = {} html_theme_options = {
# MC testing
"show_other_versions": "True",
# ...
}
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,

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

@ -14,7 +14,8 @@ Quickstart
---------- ----------
The StarlingX documentation uses reStructuredText (RST) markup syntax with The StarlingX documentation uses reStructuredText (RST) markup syntax with
Sphinx extensions. It uses the same contribution setup and workflow as the OpenStack documentation. Sphinx extensions. It uses the same contribution setup and workflow as the
OpenStack documentation.
* `OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_. * `OpenStack Documentation Contributor Guide <https://docs.openstack.org/doc-contrib-guide/index.html>`_.
@ -22,13 +23,14 @@ Sphinx extensions. It uses the same contribution setup and workflow as the OpenS
Setup for contribution Setup for contribution
********************** **********************
Follow the OpenStack instructions `Setting up for contribution <https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#setting-up-for-contribution>`_. Follow the OpenStack instructions for `setting up for contribution
<https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#setting-up-for-contribution>`_.
************* *************
Make a change Make a change
************* *************
#. Make changes following the OpenStack instructions for #. Make changes following the OpenStack instructions for:
#. `Starting a change <https://docs.openstack.org/infra/manual/developers.html#starting-a-change>`_ #. `Starting a change <https://docs.openstack.org/infra/manual/developers.html#starting-a-change>`_
#. `Committing a change <https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#committing-a-change>`_. #. `Committing a change <https://docs.openstack.org/doc-contrib-guide/quickstart/first-timers.html#committing-a-change>`_.
@ -55,11 +57,13 @@ Find tasks and help needed
If you are looking for work to complete: If you are looking for work to complete:
* Refer to the * Refer to the `StarlingX documentation StoryBoard
`StarlingX documentation StoryBoard <https://storyboard.openstack.org/#!/project/starlingx/docs>`_ for topics that need content. Many topics have stub pages in the documentation <https://storyboard.openstack.org/#!/project/starlingx/docs>`_ for topics that
with a link to the associated story. need content. Many topics have stub pages in the documentation with a link to
the associated story.
* Find open `documentation bugs on Launchpad <https://bugs.launchpad.net/starlingx/+bugs?field.tag=stx.docs>`_. * Find open `documentation bugs on Launchpad
<https://bugs.launchpad.net/starlingx/+bugs?field.tag=stx.docs>`_.
If you make a contribution that has an the associated story, task, or bug in the If you make a contribution that has an the associated story, task, or bug in the
@ -85,8 +89,8 @@ Documentation for StarlingX is organized into the following sections:
System administration and maintenance guides. System administration and maintenance guides.
:doc:`/api-ref/index` :doc:`/api-ref/index`
REST API references for the StarlingX project. For additional information about REST API references for the StarlingX project. For additional information
where REST API documentation is located, see `API documentation`_. about where REST API documentation is located, see `API documentation`_.
:doc:`/cli_ref/index` :doc:`/cli_ref/index`
Reference for the StarlingX project command line interface (CLI). Reference for the StarlingX project command line interface (CLI).
@ -104,10 +108,11 @@ Documentation for StarlingX is organized into the following sections:
API documentation API documentation
***************** *****************
The structure and location of the REST API documentation deserves extra explanation. The structure and location of the REST API documentation deserves extra
explanation.
Most REST API content is generated from the StarlingX project associated with the Most REST API content is generated from the StarlingX project associated with
API. For example, the documentation for the StarlingX metal REST API is the API. For example, the documentation for the StarlingX metal REST API is
generated from the `metal repository <https://opendev.org/starlingx/metal>`_. generated from the `metal repository <https://opendev.org/starlingx/metal>`_.
API references for StarlingX extensions are part of the docs repository, located API references for StarlingX extensions are part of the docs repository, located
@ -122,7 +127,8 @@ The ``api-ref`` project also contains index pages used by Sphinx to
generate the final content tree. Note that the REST API landing page used to generate the final content tree. Note that the REST API landing page used to
render content in the generated website is found in the ``doc`` project. render content in the generated website is found in the ``doc`` project.
For additional information on the API documentation, refer to :doc:`api_contribute_guide`. For additional information on the API documentation, refer to
:doc:`api_contribute_guide`.
****************** ******************
Spec documentation Spec documentation
@ -131,15 +137,16 @@ Spec documentation
Spec documentation is found in the Spec documentation is found in the
`Starlingx specs project <https://opendev.org/starlingx/specs>`_. `Starlingx specs project <https://opendev.org/starlingx/specs>`_.
The ``specs/2019.03`` directory contains the documentation files for approved and The ``specs/2019.03`` directory contains the documentation files for approved
implemented specs. and implemented specs.
------------- -------------
Writing style Writing style
------------- -------------
StarlingX documentation follows many (but not all!) of the writing style StarlingX documentation follows many (but not all!) of the writing style
guidelines described in the `OpenStack documentation writing style guide <https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_. Differences guidelines described in the `OpenStack documentation writing style guide
<https://docs.openstack.org/doc-contrib-guide/writing-style.html>`_. Differences
between the StarlingX and OpenStack practices are highlighted below. between the StarlingX and OpenStack practices are highlighted below.
* Use Title Case for page titles. For example: * Use Title Case for page titles. For example:
@ -150,7 +157,8 @@ between the StarlingX and OpenStack practices are highlighted below.
Documentation Contributor Guide Documentation Contributor Guide
=============================== ===============================
* Start section titles with an action verb, but not a gerund (word that ends with -ing). For example: * Start section titles with an action verb. Do not use a gerund (word that ends
with -ing). For example:
:: ::
@ -239,7 +247,7 @@ Cross-references
Cross-reference to arbitrary locations in a document using the ``ref`` role and a Cross-reference to arbitrary locations in a document using the ``ref`` role and a
named target. Named targets must precede a section heading. For more information named target. Named targets must precede a section heading. For more information
on references, see on references, see
`Internal Hyperlink Targets <http://docutils.sourceforge.net/docs/user/rst/quickref.html#internal-hyperlink-targets>`_ `Internal Hyperlink Targets <http://docutils.sourceforge.net/docs/user/rst/quickref.html#internal-hyperlink-targets>`_.
**Input:** **Input:**
@ -275,7 +283,8 @@ This is the reference to :ref:`my_named_target`.
Information blocks Information blocks
****************** ******************
Emphasize information using notices (an 'admonition' in Sphinx). Different types of notices exist to emphasize degrees of information importance. Emphasize information using notices (an *admonition* in Sphinx). Different types
of notices exist to emphasize degrees of information importance.
**Input:** **Input:**
@ -324,8 +333,8 @@ Emphasize information using notices (an 'admonition' in Sphinx). Different types
Inline elements Inline elements
*************** ***************
Format most inline elements such as filenames and paths, code fragments, parameters, or Format most inline elements such as filenames and paths, code fragments,
options with double back ticks. parameters, or options with double back ticks.
**Input:** **Input:**
:: ::
@ -347,7 +356,8 @@ for markup for other inline elements.
Lists Lists
***** *****
Use a bulleted list for a sequence of items whose order does not matter, such as a list of features. Use a bulleted list for a sequence of items whose order does not matter, such as
a list of features.
**Input:** **Input:**
@ -363,7 +373,8 @@ Use a bulleted list for a sequence of items whose order does not matter, such as
* Apple * Apple
* Orange * Orange
Use an enumerated list for a sequence of items whose order matters, such as in an ordered sequence of installation steps. Use an enumerated list for a sequence of items whose order matters, such as in
an ordered sequence of installation steps.
**Input:** **Input:**
@ -379,7 +390,8 @@ Use an enumerated list for a sequence of items whose order matters, such as in a
#. Peel apple. #. Peel apple.
#. Eat apple. #. Eat apple.
Use a definition list for an unordered list where each item has a short definition, such as term/definition pairs. Use a definition list for an unordered list where each item has a short
definition, such as term/definition pairs.
**Input:** **Input:**