michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: use pygments devicetree language support

Browse source 
Since Pygments 2.7.0 devicetree syntax is supported, so there is no need
to use a custom lexer. Version 2.9.0 introduces a fix that is required
for some devicetree snippets.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This commit is contained in:
Gerard Marull-Paretas 2021-03-17 11:21:21 +01:00 • committed by Anas Nashif
commit aa0b02bf75
12 changed files with 35 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/conf.py
View file

@ -6,7 +6,6 @@ import os
from pathlib import Path
import re
from sphinx.highlighting import lexers
import sphinx_rtd_theme
@ -32,7 +31,6 @@ sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_scripts"))
# for autodoc directives on runners.xyz.
sys.path.insert(0, str(ZEPHYR_BASE / "scripts" / "west_commands"))
from lexer.DtsLexer import DtsLexer
import redirects
try:
@ -107,8 +105,6 @@ default_role = "any"
pygments_style = "sphinx"
lexers["DTS"] = DtsLexer()
todo_include_todos = False
rst_epilog = """

4
doc/guides/dts/api-usage.rst
View file

@ -73,7 +73,7 @@ Here's a DTS fragment for some imaginary hardware we'll return to throughout
this file for examples:
.. literalinclude:: main-example.dts
:language: DTS
:language: devicetree
:start-after: start-after-here
Here are a few ways to get node identifiers for the ``i2c@40002000`` node:
@ -184,7 +184,7 @@ Properties with type ``array``, ``uint8-array``, and ``string-array`` work
similarly, except ``DT_PROP()`` expands to an array initializer in these cases.
Here is an example devicetree fragment:
.. code-block:: DTS
.. code-block:: devicetree
foo: foo@1234 {
a = <1000 2000 3000>; /* array */

24
doc/guides/dts/bindings.rst
View file

@ -44,7 +44,7 @@ A simple example
Here is an example devicetree node:
.. code-block:: DTS
.. code-block:: devicetree
/* Node in a DTS file */
bar-device {
@ -88,7 +88,7 @@ For another example, the following node would cause a build error, because it
has no ``num-foos`` property, and this property is marked required in the
binding:
.. code-block:: DTS
.. code-block:: devicetree
bad-node {
compatible = "foo-company,bar-device";
@ -103,7 +103,7 @@ match.
Take this node as an example:
.. code-block:: DTS
.. code-block:: devicetree
baz-device {
compatible = "foo-company,baz-device", "generic-baz-device";
@ -242,7 +242,7 @@ It should look like this in a binding file:
This devicetree node would match the above binding:
.. code-block:: DTS
.. code-block:: devicetree
device {
compatible = "manufacturer,device";
@ -251,7 +251,7 @@ This devicetree node would match the above binding:
Assuming no binding has ``compatible: "manufacturer,device-v2"``, it would also
match this node:
.. code-block:: DTS
.. code-block:: devicetree
device-2 {
compatible = "manufacturer,device-v2", "manufacturer,device";
@ -304,7 +304,7 @@ For example, a binding for a UART peripheral might look something like this:
The properties in the following node would be validated by the above binding:
.. code-block:: DTS
.. code-block:: devicetree
my-serial@deadbeef {
compatible = "manufacturer,serial";
@ -575,7 +575,7 @@ a binding is found for it.
Consider a binding for a PWM LED node like this one, where the child nodes are
required to have a ``pwms`` property:
.. code-block:: DTS
.. code-block:: devicetree
pwmleds {
compatible = "pwm-leds";
@ -618,7 +618,7 @@ The binding would look like this:
will apply to the ``grandchild`` node in this DTS:
.. code-block:: DTS
.. code-block:: devicetree
parent {
compatible = "foo";
@ -685,7 +685,7 @@ what bus it appears on. For example, consider a sensor device with compatible
The sensor node may therefore appear in the devicetree as a child node of
either an SPI or an I2C controller, like this:
.. code-block:: DTS
.. code-block:: devicetree
spi-bus@... {
/* ... some compatible with 'bus: spi', etc. ... */
@ -749,7 +749,7 @@ The tooling strips the final ``s`` from the property name of such properties,
resulting in ``pwm``. Then the value of the ``#pwm-cells`` property is
looked up in each of the PWM controller nodes ``pwm0`` and ``pwm3``, like so:
.. code-block:: DTS
.. code-block:: devicetree
pwm0: pwm@... {
compatible = "foo,pwm";
@ -771,7 +771,7 @@ The number of PWM cells in the specifiers in ``pwms`` must match the
``#pwm-cells`` values, as shown above. If there is a mismatch, an error is
raised. For example, this node would result in an error:
.. code-block:: DTS
.. code-block:: devicetree
my-bad-device {
/* wrong: 2 cells given in the specifier, but #pwm-cells is 1 in pwm3. */
@ -945,7 +945,7 @@ needed, such as storing a hardware-dependent value, phandle(s), or GPIO pin.
For example, with this DTS fragment:
.. code-block:: DTS
.. code-block:: devicetree
#include <dt-bindings/gpio/gpio.h>

8
doc/guides/dts/howtos.rst
View file

@ -59,7 +59,7 @@ When writing Zephyr applications, you'll often want to get a driver-level
For example, with this devicetree fragment, you might want the struct device
for ``serial@40002000``:
.. code-block:: DTS
.. code-block:: devicetree
/ {
soc {
@ -237,7 +237,7 @@ See :ref:`set-devicetree-overlays` for how to add an overlay to the build.
Overlays can override node property values in multiple ways.
For example, if your BOARD.dts contains this node:
.. code-block:: DTS
.. code-block:: devicetree
/ {
soc {
@ -504,7 +504,7 @@ labels like ``mydevice0``, ``mydevice1``, etc. appropriately for the IP blocks
your driver supports. The resulting devicetree usually looks something like
this:
.. code-block:: DTS
.. code-block:: devicetree
/ {
soc {
@ -659,7 +659,7 @@ node with path ``/soc/i2c@12340000`` in a C/C++ file:
And if you're trying to **set** that property in a devicetree overlay:
.. code-block:: DTS
.. code-block:: devicetree
/*
* foo.overlay: DTS names with special characters, etc.

12
doc/guides/dts/intro.rst
View file

@ -61,7 +61,7 @@ for this tree is called DTS (for devicetree source), and is defined in the
Here is an example DTS file:
.. code-block:: DTS
.. code-block:: devicetree
/dts-v1/;
@ -121,7 +121,7 @@ Similar conventions exist for representing other types of hardware.
The DTS would look something like this:
.. code-block:: DTS
.. code-block:: devicetree
/dts-v1/;
@ -154,7 +154,7 @@ names and properties you might see when working with I2C devices.
This is the corresponding DTS:
.. code-block:: DTS
.. code-block:: devicetree
/dts-v1/;
@ -230,7 +230,7 @@ Fixed flash partitions
The unit address is the partition's start offset within the flash memory.
For example, take this flash device and its partitions:
.. code-block:: DTS
.. code-block:: devicetree
flash@8000000 {
/* ... */
@ -423,7 +423,7 @@ Additional notes on the above:
You can write a phandle using ``&foo``, where ``foo`` is a :ref:`node label
<dt-node-labels>`. Here is an example devicetree fragment:
.. code-block:: DTS
.. code-block:: devicetree
foo: device@0 { };
device@1 {
@ -465,7 +465,7 @@ chosen node.
Here is an example devicetree which uses both:
.. code-block:: DTS
.. code-block:: devicetree
/dts-v1/;

4
doc/guides/flash_debug/host-tools.rst
View file

@ -84,7 +84,7 @@ avoid overlaps, always.
A typical flash layout for devices without a ROM bootloader is:
.. code-block:: DTS
.. code-block:: devicetree
/ {
chosen {
@ -125,7 +125,7 @@ A typical flash layout for devices without a ROM bootloader is:
A typical flash layout for devices with a ROM bootloader and storage
partition is:
.. code-block:: DTS
.. code-block:: devicetree
/ {
chosen {

6
doc/guides/porting/board_porting.rst
View file

@ -192,7 +192,7 @@ your board's name). If you're new to devicetree, see :ref:`devicetree-intro`.
In general, :file:`plank.dts` should look like this:
.. code-block:: DTS
.. code-block:: devicetree
/dts-v1/;
#include <your_soc_vendor/your_soc.dtsi>
@ -273,7 +273,7 @@ generic across K6X-based boards, it leaves many devices disabled by default
using ``status`` properties. For example, there is a CAN controller defined as
follows (with unimportant parts skipped):
.. code-block:: DTS
.. code-block:: devicetree
can0: can@40024000 {
...
@ -289,7 +289,7 @@ such as adding nodes for on-board sensors, LEDs, buttons, etc.
For example, FRDM-K64 (but not Hexiwear K64) :file:`.dts` enables the CAN
controller and sets the bus speed:
.. code-block:: DTS
.. code-block:: devicetree
&can0 {
status = "okay";

4
doc/guides/porting/shields.rst
View file

@ -53,7 +53,7 @@ This should be done at two different level:
:file:`BOARD.dts` should define a node alias for each connector interface.
For example, for Arduino I2C:
.. code-block:: DTS
.. code-block:: devicetree
#define arduino_i2c i2c1
@ -64,7 +64,7 @@ This should be done at two different level:
Note: With support of dtc v1.4.2, above will be replaced with the recently
introduced overriding node element:
.. code-block:: DTS
.. code-block:: devicetree
arduino_i2c:i2c1{};

2
doc/reference/devicetree/api.rst
View file

@ -168,7 +168,7 @@ These are recommended for use within device drivers. To use them, define
``DT_DRV_COMPAT`` to the lowercase-and-underscores compatible the device driver
implements support for. Here is an example devicetree fragment:
.. code-block:: DTS
.. code-block:: devicetree
serial@40001000 {
compatible = "vnd,serial";

2
doc/reference/storage/disk/access.rst
View file

@ -30,7 +30,7 @@ Example devicetree fragment below shows how to add SD card node to ``spi1``
interface. Example uses pin ``PA27`` for chip select, and runs the SPI bus
at 24 MHz once the SD card has been initialized:
.. code-block:: DTS
.. code-block:: devicetree
&spi1 {
status = "okay";

2
samples/basic/button/README.rst
View file

@ -40,7 +40,7 @@ Here is a minimal devicetree fragment which supports this sample. This only
includes a ``sw0`` alias; the optional ``led0`` alias is left out for
simplicity.
.. code-block:: DTS
.. code-block:: devicetree
/ {
aliases {

1
scripts/requirements-doc.txt
View file

@ -5,6 +5,7 @@ sphinx~=3.3
sphinx_rtd_theme>=0.5.2,<1.0
sphinx-tabs
sphinxcontrib-svg2pdfconverter
pygments~=2.9
# Used by zephyr_module
pykwalify