starlingx/docs
Code Issues Proposed changes

Add column conditionalization instructions (r9,r8,r7,r6)

Browse Source 
Add documentation to contributor guide for conditionalizing table columns from publishing streams.
- Clarify global limitation
- Add doc-build-context instructions

Change-Id: I4364cdbbb882612bc191e6ef29ea74d7c928625b
Signed-off-by: Ron Stone <ronald.stone@windriver.com>
This commit is contained in:
Ron Stone 2024-10-18 18:09:11 +00:00
parent 9fc33f8fe5
commit 89a9849841
3 changed files with 216 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
doc/source/_includes/build-contexts-c86d03c16918.rest Normal file
View File

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

@ -411,7 +411,7 @@ particularly useful in procedures where some steps vary across two or more
variable factors. Rather than maintain two or more separate procedures, tabs variable factors. Rather than maintain two or more separate procedures, tabs
can be used to show one of the alternate sets of content. For example, the can be used to show one of the alternate sets of content. For example, the
|prod| installation procedures make heavy use of tabs to allow the reader to |prod| installation procedures make heavy use of tabs to allow the reader to
switch between virtual and bare-metal versions of the procedures. switch between virtual and bare-metal versions of the procedures.
.. only:: starlingx .. only:: starlingx
@ -425,18 +425,18 @@ on a page.
.. code-block:: rst .. code-block:: rst
.. tabs:: .. tabs::
.. tab:: Apples .. tab:: Apples
Apples are green, or sometimes red. Apples are green, or sometimes red.
.. tab:: Pears .. tab:: Pears
Pears are green. Pears are green.
.. tab:: Oranges .. tab:: Oranges
Oranges are orange. Oranges are orange.
.. tabs:: .. tabs::
@ -452,47 +452,47 @@ on a page.
Oranges are orange. Oranges are orange.
**Nested tabs** **Nested tabs**
Tab sets can be defined within other tab sets. While this can be useful for Tab sets can be defined within other tab sets. While this can be useful for
organizing logical hierarchies of information, care should be taken not to make organizing logical hierarchies of information, care should be taken not to make
readers 'dig' for relevant content, making it unnecessarily difficult to find. readers 'dig' for relevant content, making it unnecessarily difficult to find.
.. tip:: .. tip::
Remember that the organizational goal of tabs is hide irrelevant information Remember that the organizational goal of tabs is hide irrelevant information
while *making all relevant information visible*. while *making all relevant information visible*.
.. code-block:: rst .. code-block:: rst
.. tabs:: .. tabs::
.. tab:: Stars .. tab:: Stars
.. tabs:: .. tabs::
.. tab:: The Sun .. tab:: The Sun
The closest star to us. The closest star to us.
.. tab:: Proxima Centauri .. tab:: Proxima Centauri
The second closest star to us. The second closest star to us.
.. tab:: Polaris .. tab:: Polaris
The North Star. The North Star.
.. tab:: Moons .. tab:: Moons
.. tabs:: .. tabs::
.. tab:: The Moon .. tab:: The Moon
Orbits the Earth Orbits the Earth
.. tab:: Titan .. tab:: Titan
Orbits Jupiter Orbits Jupiter
.. tabs:: .. tabs::
@ -543,45 +543,45 @@ any of the tab sets.
.. code-block:: rst .. code-block:: rst
.. tabs:: .. tabs::
.. group-tab:: Linux .. group-tab:: Linux
Linux tab content - tab set 1 Linux tab content - tab set 1
.. group-tab:: Mac OSX .. group-tab:: Mac OSX
Mac OSX tab content - tab set 1 Mac OSX tab content - tab set 1
.. group-tab:: Windows .. group-tab:: Windows
Windows tab content - tab set 1 Windows tab content - tab set 1
.. tabs:: .. tabs::
.. group-tab:: Linux .. group-tab:: Linux
Linux tab content - tab set 2 Linux tab content - tab set 2
.. group-tab:: Mac OSX .. group-tab:: Mac OSX
Mac OSX tab content - tab set 2 Mac OSX tab content - tab set 2
.. group-tab:: Windows .. group-tab:: Windows
Windows tab content - tab set 2 Windows tab content - tab set 2
.. tabs:: .. tabs::
.. group-tab:: Linux .. group-tab:: Linux
Linux tab content - tab set 3 Linux tab content - tab set 3
.. group-tab:: Mac OSX .. group-tab:: Mac OSX
Mac OSX tab content - tab set 3 Mac OSX tab content - tab set 3
.. group-tab:: Windows .. group-tab:: Windows
Windows tab content - tab set 3 Windows tab content - tab set 3
Try it out for yourself here: Try it out for yourself here:
@ -911,8 +911,8 @@ throughout the |prod| documentation.
``~(keystone_admin)]$`` ``~(keystone_admin)]$``
Used to indicate that the command must be run within the sourced environment Used to indicate that the command must be run within the sourced environment
of a system controller, i.e. after running of a system controller, i.e. after running
``$ source /etc/platform/openrc`` ``$ source /etc/platform/openrc``
------------- -------------
@ -947,7 +947,7 @@ each begins and ends:
.. begin-fragement-2 .. begin-fragement-2
This content will be inserted using ``.. include::`` example 2, below. This content will be inserted using ``.. include::`` example 2, below.
.. end-fragment-2 .. end-fragment-2
@ -1060,7 +1060,7 @@ This will result in the expected numbering sequence:
parameters work with .. pre\ |html-comment|-include::. parameters work with .. pre\ |html-comment|-include::.
* Indentation within the ``rest`` file being referenced must match the * Indentation within the ``rest`` file being referenced must match the
calling context. calling context.
* If the list is not indented, the additional step(s) to be inserted should * If the list is not indented, the additional step(s) to be inserted should
not be indented. not be indented.
@ -1126,21 +1126,21 @@ Hiding strings
To hide a string, use the ``hideable`` role. For example: To hide a string, use the ``hideable`` role. For example:
.. code-block:: .. code-block::
.. start-prepare-servers-common .. start-prepare-servers-common
Prior to starting the |prod| installation, ensure that the |bare-metal| Prior to starting the |prod| installation, ensure that the |bare-metal|
servers are in the following state: servers are in the following state:
... ...
- BIOS configured with Intel Virtualization (VTD, VTX) - BIOS configured with Intel Virtualization (VTD, VTX)
- Disabled for controller-only servers and storage servers. - Disabled for controller-only servers and storage servers.
- Enabled for :hideable:`controller+worker (All-in-one) servers and` worker servers. - Enabled for :hideable:`controller+worker (All-in-one) servers and` worker servers.
- The servers are powered off. - The servers are powered off.
.. end-prepare-servers-common .. end-prepare-servers-common
@ -1157,12 +1157,12 @@ In the ``rst`` file where you want to include the text marked up with the
Install Kubernetes Platform on All-in-one Duplex Install Kubernetes Platform on All-in-one Duplex
================================================ ================================================
... ...
-------------------------------- --------------------------------
Prepare Servers for Installation Prepare Servers for Installation
-------------------------------- --------------------------------
.. include:: /shared/_includes/prepare-servers-for-installation-91baad307173.rest .. include:: /shared/_includes/prepare-servers-for-installation-91baad307173.rest
:start\ |html-comment|-after: start-prepare-servers-common :start\ |html-comment|-after: start-prepare-servers-common
:end\ |html-comment|-before: end-prepare-servers-common :end\ |html-comment|-before: end-prepare-servers-common
@ -1192,12 +1192,12 @@ top of the file:
Install Kubernetes Platform on All-in-one Duplex Install Kubernetes Platform on All-in-one Duplex
================================================ ================================================
... ...
-------------------------------- --------------------------------
Prepare Servers for Installation Prepare Servers for Installation
-------------------------------- --------------------------------
.. include:: /shared/_includes/prepare-servers-for-installation-91baad307173.rest .. include:: /shared/_includes/prepare-servers-for-installation-91baad307173.rest
:start\ |html-comment|-after: start-prepare-servers-common :start\ |html-comment|-after: start-prepare-servers-common
:end\ |html-comment|-before: end-prepare-servers-common :end\ |html-comment|-before: end-prepare-servers-common
@ -1215,29 +1215,30 @@ will render as:
Hiding blocks Hiding blocks
************* *************
To hide a block, wrap it in a ``container`` directive with the argument ``hideable`` 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 For example, create an include file ``install-status.rest`` with the
following contents: following contents:
.. code-block:: .. code-block::
The **deploy status** field has the following values: The **deploy status** field has the following values:
.. container:: hideable .. container:: hideable
``Pre-Install`` ``Pre-Install``
This status indicates that the ISO for the subcloud is being updated by This status indicates that the ISO for the subcloud is being updated by
the Central Cloud with the boot menu parameters, and kickstart the Central Cloud with the boot menu parameters, and kickstart
configuration as specified in the ``install-values.yaml`` file. configuration as specified in the ``install-values.yaml`` file.
``Installing`` ``Installing``
This status indicates that the subcloud's ISO is being installed from This status indicates that the subcloud's ISO is being installed from
the Central Cloud to the subcloud using the Redfish Virtual Media the Central Cloud to the subcloud using the Redfish Virtual Media
service on the subcloud's |BMC|. service on the subcloud's |BMC|.
.. container:: .. container::
``Bootstrapping`` ``Bootstrapping``
This status indicates that the Ansible bootstrap of |prod-long| This status indicates that the Ansible bootstrap of |prod-long|
software on the subcloud's controller-0 is in progress. software on the subcloud's controller-0 is in progress.
@ -1261,12 +1262,14 @@ The output from ``a.rst`` will include all three definitions. The output from
.. end-conditionalize-content-across-pages .. end-conditionalize-content-across-pages
----------------------- -------------------------
Hiding empty table rows Removing empty table rows
----------------------- -------------------------
.. begin-hide-empty-rows .. begin-hide-empty-rows
.. _hide-empty-rows:
A table may occasionally contain rows with conditionalized content that applies A table may occasionally contain rows with conditionalized content that applies
only in one context, resulting in empty rows in the output from other contexts. only in one context, resulting in empty rows in the output from other contexts.
@ -1281,6 +1284,139 @@ files where you make this addition.
.. end-hide-empty-rows .. end-hide-empty-rows
----------------------
Removing table columns
----------------------
.. begin-hide-table-columns
A table may contain columns that you want to appear in one publishing context
but not another.
You can supress the output of one or more columns from a publishing context by
adding metadata to the reStructuredText file containing the table.
If the conditionalization is unidirectional, you can add the metadata directly
to the :file:`rst` file.
.. rubric:: |eg|
.. code-block:: none
.. meta::
:remove-column-from-html-table: Memory Requirements,Node
:remove-column-emptied-row: 1
:docs-build-context: starlingx
where:
``remove-column-from-html-table``
is a manditory metadata field and must contain one or more column names
separated by commas.
- Do not add spaces after commas.
- Column names are case and space sensitive. They must match the name
used in the table header row exactly.
``remove-column-emptied-row``
is an optional metadata field. If set, empty rows will also be removed
after column removal. This is usful to clean up rows that only contained
content in the removed column, and are thus left empty.
Set the value to ``1`` to enable this option. Rows will not be removed if
you set any other value or if ``remove-column-emptied-row`` does not exist.
.. note::
This feature is different from removing empty table rows using
``|hide-empty-rows|`` as described in :ref:`Removing empty table rows
<hide-empty-rows>`. In that case the removal is global to a file. In this
case it is per modified table.
``docs-build-context``
specifies the documentation build(s) for which you want to remove columns
from a reStructuredText file. For example, to remove the columns ``Memory
Requirements`` and ``Node`` from a file in the StarlingX build, set the
value to ``starlingx``. Multiple contexts must be separated by commas,
without spaces.
.. warning::
If you embed metadata directly into a reStructuredText and do not set
``docs-build-context``, then columns will be removed in all build
contexts. This is probably not what you want.
.. include:: /_includes/build-contexts-c86d03c16918.rest
You can also achieve bi or multidirectional conditionalization, such as
removing the column ``Memory Requirements`` from StarlingX builds, but removing
the column ``Node`` from the same table in some other build while leaving both
intact in a third.
To do this, instead of embedding metadata directly in the file, use an
*include* file with different metadata in each build context.
.. rubric:: |eg|
#. In the context where you want to remove ``Memory Requirements``, create an
*include* file named :file:`remove-mem-requirements-and-node-cols.rest` with
the following content:
.. code-block:: none
.. meta::
:remove-column-from-html-table: Memory Requirements
:remove-column-emptied-row: 1
.. note::
Do not use the ``docs-build-context`` option if using *include* files.
#. In the context where ``Node`` be removed, create an *include* file named
:file:`remove-mem-requirements-and-node-cols.rest` with the following
content:
.. code-block:: none
.. meta::
:remove-column-from-html-table: Node
:remove-column-emptied-row: 1
#. In the context where neither column will be removed, create an empty file
named :file:`remove-mem-requirements-and-node-cols.rest`.
#. Include this file at the beginning of the reStructuredText containing the
table:
.. code-block:: none
.. include:: remove-mem-requirements-and-node-cols.rest
The metadata will be added via the *include* file when processing the file in
each publishing context, resulting in the column ``Memory Requirements`` being
removed from one build and ``Node`` from the second. Neither column will be
removed from the third.
**Limitations:**
* This feature operates globally across all tables in input files where the
specified column names are found. Use caution to prevent a column you want to
remove from one table being removed from other tables in the file.
* The ``remove-column-emptied-row`` option removes all empty rows from
processed tables. If you are using empty rows as separators between
sections in longer tables, then this behavior may not be what you want.
* To use the ``docs-build-context``, an environment variable named
``DOCS_BUILD_CONTEXT`` must be set and readable by the build toolchain. The
value passed to ``docs-build-context`` must match the value of this variable.
* This feature will not work with tables that do not have header rows. Columns
to be removed must be named.
.. end-hide-table-columns
------------------- -------------------
RST quick reference RST quick reference
------------------- -------------------
@ -1564,7 +1700,7 @@ Release notes updates
Various sections in the |prod| release notes must be updated on the ``master`` Various sections in the |prod| release notes must be updated on the ``master``
branch before the release branch for the upcoming release (for example branch before the release branch for the upcoming release (for example
``r/stx.9.0``) is created. ``r/stx.9.0``) is created.
The Release notes can be found in the directory The Release notes can be found in the directory
:file:`doc/source/releasenotes`. :file:`doc/source/releasenotes`.
@ -1605,7 +1741,7 @@ To do so:
#. On a working branch, open the file :file:`doc/source/conf.py`. #. On a working branch, open the file :file:`doc/source/conf.py`.
#. If you are updating on a new branch, change the configuration assignment #. If you are updating on a new branch, change the configuration assignment
``starlingxdocs_plus_this_version`` to the name of the new branch. ``starlingxdocs_plus_this_version`` to the name of the new branch.
For example: For example:
@ -1621,11 +1757,11 @@ To do so:
This assignment takes a *key,value* pair for each branch other than the This assignment takes a *key,value* pair for each branch other than the
branch you are configuring. branch you are configuring.
* Each key is the name of the branch that will appear in the menu. * Each key is the name of the branch that will appear in the menu.
* Each value is the name of the branch. * Each value is the name of the branch.
For example, if you are editing :file:`conf.py` on the branch ``r/stx.7.0``, For example, if you are editing :file:`conf.py` on the branch ``r/stx.7.0``,
then this assignment would container a key pair for each of then this assignment would container a key pair for each of
``r/stx.6.0``, ``r/stx.8.0``, ``<newer-release>`` ..., and ``master``. ``r/stx.6.0``, ``r/stx.8.0``, ``<newer-release>`` ..., and ``master``.
@ -1653,7 +1789,7 @@ Adding the promte job
********************* *********************
A ``promote`` job must be created for merged reviews on a new release branch to A ``promote`` job must be created for merged reviews on a new release branch to
be published to docs.starlingx.io. be published to docs.starlingx.io.
.. rubric:: |prereq| .. rubric:: |prereq|
@ -1679,10 +1815,10 @@ You must have the OpenStack ``project-config`` repo available.
description: | description: |
Promote content from openstack-tox-docs job for Promote content from openstack-tox-docs job for
starlingx/doc repository only. starlingx/doc repository only.
Publish the results of a sphinx build to Publish the results of a sphinx build to
/afs/.openstack.org/project/starlingx.io/www /afs/.openstack.org/project/starlingx.io/www
final: true final: true
vars: vars:
download_artifact_job: openstack-tox-docs download_artifact_job: openstack-tox-docs

2
tox.ini
View File

@ -35,7 +35,7 @@ commands =
bash hw-updates.sh bash hw-updates.sh
# bash hide-empty-rows.sh doc/build/html # bash hide-empty-rows.sh doc/build/html
bash -c 'python hide-empty-rows.py $(grep -rl --include="*.html" "post-build-hide-empty-table-rows" doc/build/html/*)' bash -c 'python hide-empty-rows.py $(grep -rl --include="*.html" "post-build-hide-empty-table-rows" doc/build/html/*)'
bash -c 'python hide-table-columns.py $(grep -rl --include="*.html" remove-column-from-html-table doc/build/html/*)' bash -c 'python hide-table-columns.py $(grep -rl --include=*.html --exclude=doc_contribute_guide.html remove-column-from-html-table doc/build/html/*)'
bash htmlChecks.sh doc/build/html bash htmlChecks.sh doc/build/html
[testenv:docs] [testenv:docs]