Update Contributor Guide
Add documentation of - content reuse - block content conditionalization - span content conditionalization - .. pre-include: usage - add sectioning comments Signed-off-by: Ron Stone <ronald.stone@windriver.com> Change-Id: I2372c73354f0b87c728466893cdafeb88d1f3b01
This commit is contained in:
Ron Stone
parent
b63fb82c89
commit
a7927db517
|
|
@ -146,6 +146,8 @@ and implemented specs.
|
|||
Writing style
|
||||
-------------
|
||||
|
||||
.. begin-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
|
||||
|
|
@ -168,12 +170,16 @@ between the StarlingX and OpenStack practices are highlighted below.
|
|||
Configure endpoint
|
||||
------------------
|
||||
|
||||
.. end-writing-style
|
||||
|
||||
.. _create-rst-files:
|
||||
|
||||
----------------
|
||||
Create rST Files
|
||||
----------------
|
||||
|
||||
.. begin-create-rst-files
|
||||
|
||||
Use the :command:`tox -e newfile` command to create new |RST| files.
|
||||
|
||||
.. rubric:: |context|
|
||||
|
|
@ -313,10 +319,14 @@ title is preserved as typed. No label was added if you selected :kbd:`f`.
|
|||
When you reference this file in ``toctree`` and ``ref`` directives, use
|
||||
the file name/label string like this: ``architectural-considerations--d9dd4c105700``
|
||||
|
||||
.. end-create-rst-files
|
||||
|
||||
------------------------
|
||||
Automated quality checks
|
||||
------------------------
|
||||
|
||||
.. begin-automated-quality-checks
|
||||
|
||||
Several automated checks are available to help improve and maintain the quality
|
||||
of your documentation.
|
||||
|
||||
|
|
@ -556,6 +566,8 @@ This file contains one term per line.
|
|||
changes must be submitted for review and merge via a :program:`gerrit`
|
||||
review.
|
||||
|
||||
.. end-automated-quality-checks
|
||||
|
||||
---------------
|
||||
RST conventions
|
||||
---------------
|
||||
|
|
@ -571,6 +583,351 @@ documents:
|
|||
* `Sphinx documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
|
||||
* `reStructuredText primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
|
||||
|
||||
-------------
|
||||
Content reuse
|
||||
-------------
|
||||
|
||||
.. _using-includes:
|
||||
|
||||
Content can be reused in multiple places using the Sphinx ``.. include::``
|
||||
directive.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block::
|
||||
|
||||
.. include:: /_includes/my_reusable_content.rest
|
||||
|
||||
"Include" files must not end in ``.rst``. The StarlingX convention is to use
|
||||
``.rest``.
|
||||
|
||||
You can store multiple fragements of content in a single include file and use
|
||||
them in various places. To do this, use ``rst`` comments to deliniate where
|
||||
each begins and ends:
|
||||
|
||||
.. code-block::
|
||||
|
||||
.. begin-fragement-1
|
||||
|
||||
This content will be inserted using ``.. include::`` example 1, below.
|
||||
|
||||
.. end-fragment-1
|
||||
|
||||
.. begin-fragement-2
|
||||
|
||||
This content will be inserted using ``.. include::`` example 2, below.
|
||||
|
||||
.. end-fragment-2
|
||||
|
||||
To use one or the other in an ``rst`` topic, use the *start after*
|
||||
and *end before* parameters as shown below:
|
||||
|
||||
.. rubric:: **Example 1**
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
========
|
||||
My Topic
|
||||
========
|
||||
|
||||
Integer sed tortor nisi. Vivamus feugiat, urna in posuere gravida, ligula
|
||||
nunc hendrerit magna, nec tristique ex tortor non lorem.
|
||||
|
||||
...
|
||||
|
||||
.. include:: /_includes/my_reusable_content.rest
|
||||
:start\ |html-comment|-after: begin-fragement-1
|
||||
:end\ |html-comment|-before: end-fragement-1
|
||||
|
||||
.. rubric:: **Example 2**
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
==============
|
||||
My Other Topic
|
||||
==============
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
||||
|
||||
...
|
||||
|
||||
.. include:: /_includes/my_reusable_content.rest
|
||||
:start\ |html-comment|-after: begin-fragement-2
|
||||
:end\ |html-comment|-before: end-fragement-2
|
||||
|
||||
**********************
|
||||
Content reuse in steps
|
||||
**********************
|
||||
|
||||
.. begin-content--in-steps
|
||||
|
||||
Inserting reusable or conditional steps in a numbered list context causes the
|
||||
list to restart. For example:
|
||||
|
||||
An include file, ``mysteps.rest``, containing:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. begin-step
|
||||
|
||||
#. Blue
|
||||
|
||||
.. end-step
|
||||
|
||||
used in an ``rst`` file as follows:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
#. Orange
|
||||
|
||||
#. Red
|
||||
|
||||
.. include:: mysteps.rest
|
||||
:start\ |html-comment|-after: begin-step
|
||||
:end\ |html-comment|-before: end-step
|
||||
|
||||
#. Green
|
||||
|
||||
Results in:
|
||||
|
||||
1. Orange
|
||||
|
||||
2. Red
|
||||
|
||||
1. Blue
|
||||
|
||||
2. Green
|
||||
|
||||
To avoid this, use substitute .. pre\ |html-comment|-include:: for ``.. include::``
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
#. Orange
|
||||
|
||||
#. Red
|
||||
|
||||
.. pre\ |html-comment|-include:: mysteps.rest
|
||||
:start\ |html-comment|-after: begin-step
|
||||
:end\ |html-comment|-before: end-step
|
||||
|
||||
#. Green
|
||||
|
||||
This will result in the expected numbering sequence:
|
||||
|
||||
1. Orange
|
||||
|
||||
2. Red
|
||||
|
||||
3. Blue
|
||||
|
||||
4. Green
|
||||
|
||||
.. note::
|
||||
|
||||
* Only the start\ |html-comment|-after and end\ |html-comment|-before paramters work with ..
|
||||
pre\ |html-comment|-include::.
|
||||
|
||||
* Indentation within the ``rest`` file being referenced must match the calling context.
|
||||
|
||||
* If the list is not indented, the additional step(s) to be inserted should
|
||||
not be indented.
|
||||
|
||||
* If the list is indented (a sublist or in a nested block context), the
|
||||
same indentation must be applied to the additional steps.
|
||||
|
||||
.. end-content--in-steps
|
||||
|
||||
--------------------------
|
||||
Content conditionalization
|
||||
--------------------------
|
||||
|
||||
****************************
|
||||
Conditionalize across builds
|
||||
****************************
|
||||
|
||||
.. begin-conditionalize-content-across-builds
|
||||
|
||||
If you need to conditionalize some content to be used in a specific build
|
||||
context, such as StarlingX or a 3rd party build that reuses StarlingX content,
|
||||
you can use the ``.. only::`` directive.
|
||||
|
||||
For example:
|
||||
|
||||
.. code-block::
|
||||
|
||||
.. only:: starlingx
|
||||
|
||||
Integer sed tortor nisi. Vivamus feugiat, urna in posuere gravida, ligula
|
||||
nunc hendrerit magna, nec tristique ex tortor non lorem.
|
||||
|
||||
Three build contexts are available:
|
||||
|
||||
``starlingx``
|
||||
Content will be included in the standard StarlingX documentation build.
|
||||
|
||||
``partner``
|
||||
Content will be excluded from the StarlingX documentation build. To reuse
|
||||
this content in a 3rd party build, ensure that the ``partner`` tag is based
|
||||
to the builder.
|
||||
|
||||
``openstack``
|
||||
Content will be included in an OpenStack documentation context. This content
|
||||
is included in the StarlingX documentation build.
|
||||
|
||||
.. end-conditionalize-content-across-builds
|
||||
|
||||
***************************
|
||||
Conditionalize across pages
|
||||
***************************
|
||||
|
||||
.. begin-conditionalize-content-across-pages
|
||||
|
||||
If you want to reuse a block of content in multiple ``rst`` files from the same
|
||||
build using ``.. include::`` directives, but need to exclude specific strings
|
||||
from one of those locations, you can use the ``hideable`` role and substitution.
|
||||
|
||||
You can hide both strings and blocks (paragraphs etc.).
|
||||
|
||||
Hiding strings
|
||||
**************
|
||||
|
||||
To hide a string, use the ``hideable`` role. For example:
|
||||
|
||||
.. code-block::
|
||||
|
||||
.. start-prepare-servers-common
|
||||
|
||||
Prior to starting the |prod| installation, ensure that the |bare-metal|
|
||||
servers are in the following state:
|
||||
|
||||
...
|
||||
|
||||
- BIOS configured with Intel Virtualization (VTD, VTX)
|
||||
|
||||
- Disabled for controller-only servers and storage servers.
|
||||
|
||||
- Enabled for :hideable:`controller+worker (All-in-one) servers and` worker servers.
|
||||
|
||||
- The servers are powered off.
|
||||
|
||||
.. end-prepare-servers-common
|
||||
|
||||
In the ``rst`` file where you want to include the text marked up with the
|
||||
``:hideable:`` role, simply insert the content using the :ref:`include
|
||||
<using-includes>` directive:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
.. _aio_duplex_install_kubernetes_r7:
|
||||
|
||||
================================================
|
||||
Install Kubernetes Platform on All-in-one Duplex
|
||||
================================================
|
||||
|
||||
...
|
||||
|
||||
--------------------------------
|
||||
Prepare Servers for Installation
|
||||
--------------------------------
|
||||
|
||||
.. include:: /shared/_includes/prepare-servers-for-installation-91baad307173.rest
|
||||
:start\ |html-comment|-after: start-prepare-servers-common
|
||||
:end\ |html-comment|-before: end-prepare-servers-common
|
||||
|
||||
...
|
||||
|
||||
The bullet:
|
||||
|
||||
``- Enabled for :hideable:`controller+worker (All-in-one) servers and` worker servers.``
|
||||
|
||||
will render as:
|
||||
|
||||
- Enabled for controller+worker (All-in-one) servers and worker servers.
|
||||
|
||||
|
||||
In the ``rst`` file where you want to suppress the text marked up with the
|
||||
``:hideable:`` role, do the same, but add the ``|hideable|`` substitution at the
|
||||
top of the file:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
\|hideable\|
|
||||
|
||||
.. _aio_duplex_install_kubernetes_r7:
|
||||
|
||||
================================================
|
||||
Install Kubernetes Platform on All-in-one Duplex
|
||||
================================================
|
||||
|
||||
...
|
||||
|
||||
--------------------------------
|
||||
Prepare Servers for Installation
|
||||
--------------------------------
|
||||
|
||||
.. include:: /shared/_includes/prepare-servers-for-installation-91baad307173.rest
|
||||
:start\ |html-comment|-after: start-prepare-servers-common
|
||||
:end\ |html-comment|-before: end-prepare-servers-common
|
||||
|
||||
...
|
||||
|
||||
The bullet:
|
||||
|
||||
``- Enabled for :hideable:`controller+worker (All-in-one) servers and` worker servers.``
|
||||
|
||||
will render as:
|
||||
|
||||
- Enabled for worker servers.
|
||||
|
||||
Hiding blocks
|
||||
*************
|
||||
|
||||
To hide a block, wrap it in a ``container`` directive with the argument ``hideable``
|
||||
|
||||
For example, create an include file ``install-status.rest`` with the
|
||||
following contents:
|
||||
|
||||
.. code-block::
|
||||
|
||||
The **deploy status** field has the following values:
|
||||
|
||||
.. container:: hideable
|
||||
|
||||
``Pre-Install``
|
||||
This status indicates that the ISO for the subcloud is being updated by
|
||||
the Central Cloud with the boot menu parameters, and kickstart
|
||||
configuration as specified in the ``install-values.yaml`` file.
|
||||
|
||||
``Installing``
|
||||
This status indicates that the subcloud's ISO is being installed from
|
||||
the Central Cloud to the subcloud using the Redfish Virtual Media
|
||||
service on the subcloud's |BMC|.
|
||||
|
||||
.. container::
|
||||
|
||||
``Bootstrapping``
|
||||
This status indicates that the Ansible bootstrap of |prod-long|
|
||||
software on the subcloud's controller-0 is in progress.
|
||||
|
||||
and load it in two different contexts:
|
||||
|
||||
.. code-block::
|
||||
:caption: a.rst
|
||||
|
||||
.. include:: install-status.rest
|
||||
|
||||
.. code-block::
|
||||
:caption: b.rst
|
||||
|
||||
|hideable|
|
||||
|
||||
.. include:: install-status.rest
|
||||
|
||||
The output from ``a.rst`` will include all three definitions. The output from
|
||||
``b.rst`` will include only the ``bootstrap`` definition.
|
||||
|
||||
.. end-conditionalize-content-across-pages
|
||||
|
||||
-------------------
|
||||
RST quick reference
|
||||
-------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue