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 <[email protected]>
andak · Sep 18, 2019 · f652129 · f652129
1 parent c0ae674
commit f652129
Show file tree

Hide file tree

Showing 10 changed files with 44 additions and 50 deletions.
diff --git a/boards/arm/mps2_an385/doc/index.rst b/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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - D0 : EXT_0
    - D1 : EXT_4
@@ -206,8 +205,7 @@ Mapping from the ARM MPS2 Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - UART_3_RX : D0
    - UART_3_TX : D1

diff --git a/boards/arm/mps2_an521/doc/index.rst b/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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - D0 : EXT_0
    - D1 : EXT_4
@@ -248,8 +247,7 @@ Mapping from the ARM MPS2+ AN521 Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - UART_3_RX : D0
    - UART_3_TX : D1
@@ -282,8 +280,7 @@ System Clock
 
 MPS2+ AN521 has several clocks connected:
 
-.. hlist::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - MAINCLK : 20MHz
    - SYSCLK : 20MHz

diff --git a/boards/arm/v2m_beetle/doc/index.rst b/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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - D0 : P0_0
    - D1 : P0_1
@@ -173,8 +172,7 @@ Mapping from the ARM V2M Beetle Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - UART_0_RX : D0
    - UART_0_TX : D1

diff --git a/boards/arm/v2m_musca/doc/index.rst b/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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - D0 : P0_0
    - D1 : P0_1
@@ -213,8 +212,7 @@ Mapping from the ARM V2M Musca Board pins to GPIO controllers:
 
 Peripheral Mapping:
 
-.. hlist::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - UART_0_RX : D0
    - UART_0_TX : D1

diff --git a/boards/arm/v2m_musca_b1/doc/index.rst b/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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - 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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - UART_0_RX : D0
    - UART_0_TX : D1

diff --git a/doc/guides/c_library.rst b/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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    - abs()
    - atoi()

diff --git a/doc/guides/coccinelle.rst b/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

diff --git a/doc/guides/documentation/index.rst b/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,
-you can indicate the list items should be rendered in multiple columns
-with a special ``hlist`` directive::
+If you have a long bullet list of items, where each item is short, you
+can indicate the list items should be rendered in multiple columns with
+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::
-      :columns: 3
+   .. rst-class:: rst-columns
 
       * 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::
-   :columns: 3
+.. rst-class:: rst-columns
 
    * 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
-all the list items are indented by three spaces.
+The number of columns displayed will change based on the available width
+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
 ******

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

diff --git a/doc/static/zephyr-custom.css b/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;
+}