michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: replace hlist with column-width class

Browse source 
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>
This commit is contained in:
David B. Kinder 2019-09-17 14:19:02 -07:00 • committed by Anas Nashif
commit f6521290e6
10 changed files with 44 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

6
boards/arm/mps2_an385/doc/index.rst
View file

@ -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

11
boards/arm/mps2_an521/doc/index.rst
View file

@ -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

6
boards/arm/v2m_beetle/doc/index.rst
View file

@ -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

8
boards/arm/v2m_musca/doc/index.rst
View file

@ -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

8
boards/arm/v2m_musca_b1/doc/index.rst
View file

@ -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

3
doc/guides/c_library.rst
View file

@ -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()

2
doc/guides/coccinelle.rst
View file

@ -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

23
doc/guides/documentation/index.rst
View file

@ -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
******

18
doc/releases/release-notes-2.0.rst
View file

@ -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::
:columns: 3
.. rst-class:: rst-columns
* emsdp
* hsdk
@ -111,8 +110,7 @@ Boards & SoC Support
* 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

9
doc/static/zephyr-custom.css vendored
View file

@ -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;
}