doc: replace hlist with column-width class

For long lists of items, it's better to use a multi-column display to
make better use of the screen space.  We used the hlist directive to
accomplish list, but it has a drawback on small (phone) screens because
under the hood, the rendering is done using tables.

Instead, we can take advantage of built-in CSS multi-column support
available in recent browsers.  So, convert uses of the hlist directive
to use an rst-class directive to apply a multi-column class to
the entity. The chosen column-width (18em) gives us a 3-column display
on typical window sizes, but will adjust to more or fewer columns
depending on the actual real estate available.

Also, update the documentation guidelines to mention this change.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

boards/arm/mps2_an385/doc/index.rst

@@ -148,8 +148,7 @@ All GPIO controller pins are exposed via the following sequence of pin numbers:
 
 Mapping from the ARM MPS2 Board pins to GPIO controllers:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - D0 : EXT_0
    - D1 : EXT_4
@@ -206,8 +205,7 @@ Mapping from the ARM MPS2 Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - UART_3_RX : D0
    - UART_3_TX : D1

boards/arm/mps2_an521/doc/index.rst

@@ -144,7 +144,7 @@ in the following table:
 |      |            | attempt to ARM |                          |
 |      |            | mode           |                          |
 +------+------------+----------------+--------------------------+
-|  7   |SecureFault | Unauthorized   | system fatal error       |
+|  7   | SecureFault| Unauthorized   | system fatal error       |
 |      |            | access to      |                          |
 |      |            | secure region  |                          |
 |      |            | from ns space  |                          |
@@ -190,8 +190,7 @@ All GPIO controller pins are exposed via the following sequence of pin numbers:
 
 Mapping from the ARM MPS2+ AN521 Board pins to GPIO controllers:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - D0 : EXT_0
    - D1 : EXT_4
@@ -248,8 +247,7 @@ Mapping from the ARM MPS2+ AN521 Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - UART_3_RX : D0
    - UART_3_TX : D1
@@ -282,8 +280,7 @@ System Clock
 
 MPS2+ AN521 has several clocks connected:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - MAINCLK : 20MHz
    - SYSCLK : 20MHz

boards/arm/v2m_beetle/doc/index.rst

@@ -135,8 +135,7 @@ All GPIO controller pins are exposed via the following sequence of pin numbers:
 
 Mapping from the ARM V2M Beetle Board pins to GPIO controllers:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - D0 : P0_0
    - D1 : P0_1
@@ -173,8 +172,7 @@ Mapping from the ARM V2M Beetle Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - UART_0_RX : D0
    - UART_0_TX : D1

boards/arm/v2m_musca/doc/index.rst

@@ -132,7 +132,7 @@ in the following table:
 |      |            | attempt to ARM |                          |
 |      |            | mode           |                          |
 +------+------------+----------------+--------------------------+
-|  7   |SecureFault | Unauthorized   | system fatal error       |
+|  7   | SecureFault| Unauthorized   | system fatal error       |
 |      |            | access to      |                          |
 |      |            | secure region  |                          |
 |      |            | from ns space  |                          |
@@ -175,8 +175,7 @@ All GPIO controller pins are exposed via the following sequence of pin numbers:
 
 Mapping from the ARM V2M Musca Board pins to GPIO controllers:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - D0 : P0_0
    - D1 : P0_1
@@ -213,8 +212,7 @@ Mapping from the ARM V2M Musca Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - UART_0_RX : D0
    - UART_0_TX : D1

boards/arm/v2m_musca_b1/doc/index.rst

@@ -132,7 +132,7 @@ in the following table:
 |      |            | attempt to ARM |                          |
 |      |            | mode           |                          |
 +------+------------+----------------+--------------------------+
-|  7   |SecureFault | Unauthorized   | system fatal error       |
+|  7   | SecureFault| Unauthorized   | system fatal error       |
 |      |            | access to      |                          |
 |      |            | secure region  |                          |
 |      |            | from ns space  |                          |
@@ -174,8 +174,7 @@ All GPIO controller pins are exposed via the following sequence of pin numbers:
 
 Mapping from the ARM V2M Musca B1 Board pins to GPIO controllers:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - D0 : P0_0
    - D1 : P0_1
@@ -196,8 +195,7 @@ Mapping from the ARM V2M Musca B1 Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - UART_0_RX : D0
    - UART_0_TX : D1

doc/guides/c_library.rst

@@ -28,8 +28,7 @@ functions needed by Zephyr.
 The following functions are implemented in the minimal C
 library included with Zephyr:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    - abs()
    - atoi()

doc/guides/coccinelle.rst

@@ -26,7 +26,7 @@ the Coccinelle files and ``coccicheck`` have been updated.
 Coccinelle is available through the package manager
 of many distributions, e.g. :
 
-.. hlist::
+.. rst-class:: rst-columns
 
    * Debian
    * Fedora

doc/guides/documentation/index.rst

@@ -127,12 +127,14 @@ Would be rendered as:
 Multi-column lists
 ******************
 
-If you have a long bullet list of items, where each item is short,
+If you have a long bullet list of items, where each item is short, you
-you can indicate the list items should be rendered in multiple columns
+can indicate the list items should be rendered in multiple columns with
-with a special ``hlist`` directive::
+a special ``.. rst-class:: rst-columns`` directive.  The content under
+this directive can be indented as shown, otherwise the directive will
+apply to the next non-comment element (e.g., paragraph). For example,
+this unordered list::
 
-   .. hlist::
+   .. rst-class:: rst-columns
-      :columns: 3
 
       * A list of
       * short items
@@ -144,10 +146,9 @@ with a special ``hlist`` directive::
       * space on
       * the page
 
-This would be rendered as:
+would be rendered as:
 
-.. hlist::
+.. rst-class:: rst-columns
-   :columns: 3
 
    * A list of
    * short items
@@ -159,8 +160,10 @@ This would be rendered as:
    * space on
    * the page
 
-Note the optional ``:columns:`` parameter (default is two columns), and
+The number of columns displayed will change based on the available width
-all the list items are indented by three spaces.
+of the display window, reducing to one column on narrow (phone) screens
+if necessary.  We've deprecated use of the ``hlist`` directive because it
+misbehaves on smaller screens.
 
 Tables
 ******

doc/releases/release-notes-2.0.rst

@@ -102,8 +102,7 @@ Boards & SoC Support
 * Added native_posix_64: A 64 bit variant of native_posix
 * Added support for these ARC boards:
 
-  .. hlist::
+  .. rst-class:: rst-columns
-     :columns: 3
 
      * emsdp
      * hsdk
@@ -111,8 +110,7 @@ Boards & SoC Support
 
 * Added support for these ARM boards:
 
-  .. hlist::
+  .. rst-class:: rst-columns
-     :columns: 3
 
      * atsamr21_xpro
      * cc1352r1_launchxl
@@ -138,8 +136,7 @@ Boards & SoC Support
 
 * Added support for these RISC-V boards:
 
-  .. hlist::
+  .. rst-class:: rst-columns
-     :columns: 3
 
      * hifive1_revb
      * litex_vexriscv
@@ -149,8 +146,7 @@ Boards & SoC Support
 
 * Added support for these following shields:
 
-  .. hlist::
+  .. rst-class:: rst-columns
-     :columns: 3
 
      * frdm_cr20a
      * link_board_can
@@ -160,8 +156,7 @@ Boards & SoC Support
 
 * Removed support for these boards:
 
-  .. hlist::
+  .. rst-class:: rst-columns
-     :columns: 3
 
      * arduino_101
      * arduino_101_sss
@@ -398,8 +393,7 @@ Networking
 * OpenThread updates and fixes.
 * Network device driver fixes for:
 
-  .. hlist::
+  .. rst-class:: rst-columns
-     :columns: 3
 
      - Ethernet e1000
      - Ethernet enc28j60

doc/static/zephyr-custom.css

@@ -248,3 +248,12 @@ kbd
    font-size: 4rem;
    color: mediumslateblue;
 }
+
+/* add a class for multi-column support
+ * in docs to replace use of .hlist with
+ * a .. rst-class:: rst-columns
+ */
+
+.rst-columns {
+   column-width: 18em;
+}