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 <ronald.stone@windriver.com>

doc/source/contributor/doc_contribute_guide.rst

@@ -1215,7 +1215,8 @@ 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:
@@ -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
+      <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
 -------------------

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]