From 89a9849841216e617add0c9dbd7e905aadd74556 Mon Sep 17 00:00:00 2001 From: Ron Stone Date: Fri, 18 Oct 2024 18:09:11 +0000 Subject: [PATCH] Add column conditionalization instructions (r9,r8,r7,r6) 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 --- .../build-contexts-c86d03c16918.rest | 0 .../contributor/doc_contribute_guide.rst | 294 +++++++++++++----- tox.ini | 2 +- 3 files changed, 216 insertions(+), 80 deletions(-) create mode 100644 doc/source/_includes/build-contexts-c86d03c16918.rest diff --git a/doc/source/_includes/build-contexts-c86d03c16918.rest b/doc/source/_includes/build-contexts-c86d03c16918.rest new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/contributor/doc_contribute_guide.rst b/doc/source/contributor/doc_contribute_guide.rst index ecfe1c204..96d8f1811 100644 --- a/doc/source/contributor/doc_contribute_guide.rst +++ b/doc/source/contributor/doc_contribute_guide.rst @@ -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 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 -switch between virtual and bare-metal versions of the procedures. +switch between virtual and bare-metal versions of the procedures. .. only:: starlingx @@ -425,18 +425,18 @@ on a page. .. code-block:: rst .. tabs:: - + .. tab:: Apples - + Apples are green, or sometimes red. - + .. tab:: Pears - + Pears are green. - + .. tab:: Oranges - - Oranges are orange. + + Oranges are orange. .. tabs:: @@ -452,47 +452,47 @@ on a page. Oranges are orange. -**Nested tabs** +**Nested tabs** 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 readers 'dig' for relevant content, making it unnecessarily difficult to find. .. tip:: - + 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 .. tabs:: - + .. tab:: Stars - + .. tabs:: - + .. tab:: The Sun - + The closest star to us. - + .. tab:: Proxima Centauri - + The second closest star to us. - + .. tab:: Polaris - + The North Star. - + .. tab:: Moons - + .. tabs:: - + .. tab:: The Moon - + Orbits the Earth - + .. tab:: Titan - + Orbits Jupiter .. tabs:: @@ -543,45 +543,45 @@ any of the tab sets. .. code-block:: rst .. tabs:: - + .. group-tab:: Linux - + Linux tab content - tab set 1 - + .. group-tab:: Mac OSX - + Mac OSX tab content - tab set 1 - + .. group-tab:: Windows - + Windows tab content - tab set 1 - + .. tabs:: - + .. group-tab:: Linux - + Linux tab content - tab set 2 - + .. group-tab:: Mac OSX - + Mac OSX tab content - tab set 2 - + .. group-tab:: Windows - + Windows tab content - tab set 2 - + .. tabs:: - + .. group-tab:: Linux - + Linux tab content - tab set 3 - + .. group-tab:: Mac OSX - + Mac OSX tab content - tab set 3 - + .. group-tab:: Windows - + Windows tab content - tab set 3 Try it out for yourself here: @@ -911,8 +911,8 @@ throughout the |prod| documentation. ``~(keystone_admin)]$`` 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`` ------------- @@ -947,7 +947,7 @@ each begins and ends: .. 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 @@ -1060,7 +1060,7 @@ This will result in the expected numbering sequence: parameters work with .. pre\ |html-comment|-include::. * 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 not be indented. @@ -1126,21 +1126,21 @@ Hiding strings To hide a string, use the ``hideable`` role. For example: -.. code-block:: +.. 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 @@ -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 ================================================ - ... + ... -------------------------------- 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 @@ -1192,12 +1192,12 @@ top of the file: 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 @@ -1215,29 +1215,30 @@ will render as: 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 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. @@ -1261,12 +1262,14 @@ The output from ``a.rst`` will include all three definitions. The output from .. end-conditionalize-content-across-pages ------------------------ -Hiding empty table rows ------------------------ +------------------------- +Removing empty table rows +------------------------- .. begin-hide-empty-rows +.. _hide-empty-rows: + 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. @@ -1281,6 +1284,139 @@ files where you make this addition. .. 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 + `. 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 ------------------- @@ -1564,7 +1700,7 @@ Release notes updates Various sections in the |prod| release notes must be updated on the ``master`` 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 :file:`doc/source/releasenotes`. @@ -1605,7 +1741,7 @@ To do so: #. On a working branch, open the file :file:`doc/source/conf.py`. #. 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: @@ -1621,11 +1757,11 @@ To do so: This assignment takes a *key,value* pair for each branch other than the 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. - + 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``, ```` ..., 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 -be published to docs.starlingx.io. +be published to docs.starlingx.io. .. rubric:: |prereq| @@ -1679,10 +1815,10 @@ You must have the OpenStack ``project-config`` repo available. description: | Promote content from openstack-tox-docs job for starlingx/doc repository only. - + Publish the results of a sphinx build to - /afs/.openstack.org/project/starlingx.io/www - + /afs/.openstack.org/project/starlingx.io/www + final: true vars: download_artifact_job: openstack-tox-docs diff --git a/tox.ini b/tox.ini index 52064e62f..175d9960b 100644 --- a/tox.ini +++ b/tox.ini @@ -35,7 +35,7 @@ commands = bash hw-updates.sh # 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-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 [testenv:docs]