From aa0b02bf7540880dc1bec67c6e3b8c08c66ec180 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Wed, 17 Mar 2021 11:21:21 +0100 Subject: [PATCH] doc: use pygments devicetree language support 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 --- doc/conf.py | 4 ---- doc/guides/dts/api-usage.rst | 4 ++-- doc/guides/dts/bindings.rst | 24 ++++++++++++------------ doc/guides/dts/howtos.rst | 8 ++++---- doc/guides/dts/intro.rst | 12 ++++++------ doc/guides/flash_debug/host-tools.rst | 4 ++-- doc/guides/porting/board_porting.rst | 6 +++--- doc/guides/porting/shields.rst | 4 ++-- doc/reference/devicetree/api.rst | 2 +- doc/reference/storage/disk/access.rst | 2 +- samples/basic/button/README.rst | 2 +- scripts/requirements-doc.txt | 1 + 12 files changed, 35 insertions(+), 38 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index d2d9b6f216c..b001b37c3fc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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 = """ diff --git a/doc/guides/dts/api-usage.rst b/doc/guides/dts/api-usage.rst index 8abb631f0ce..3a9fd9152a8 100644 --- a/doc/guides/dts/api-usage.rst +++ b/doc/guides/dts/api-usage.rst @@ -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 */ diff --git a/doc/guides/dts/bindings.rst b/doc/guides/dts/bindings.rst index b4f11ab826f..90f9e21e2ab 100644 --- a/doc/guides/dts/bindings.rst +++ b/doc/guides/dts/bindings.rst @@ -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 diff --git a/doc/guides/dts/howtos.rst b/doc/guides/dts/howtos.rst index 1eb7ecdba90..71141d86ab0 100644 --- a/doc/guides/dts/howtos.rst +++ b/doc/guides/dts/howtos.rst @@ -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. diff --git a/doc/guides/dts/intro.rst b/doc/guides/dts/intro.rst index f668b0b375d..0ae2c8490b7 100644 --- a/doc/guides/dts/intro.rst +++ b/doc/guides/dts/intro.rst @@ -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 `. 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/; diff --git a/doc/guides/flash_debug/host-tools.rst b/doc/guides/flash_debug/host-tools.rst index 8c856b51a98..05f2363dd0f 100644 --- a/doc/guides/flash_debug/host-tools.rst +++ b/doc/guides/flash_debug/host-tools.rst @@ -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 { diff --git a/doc/guides/porting/board_porting.rst b/doc/guides/porting/board_porting.rst index 4e3b68cfab6..dcab607aa2a 100644 --- a/doc/guides/porting/board_porting.rst +++ b/doc/guides/porting/board_porting.rst @@ -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 @@ -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"; diff --git a/doc/guides/porting/shields.rst b/doc/guides/porting/shields.rst index 8444bd9e810..8647ee5e875 100644 --- a/doc/guides/porting/shields.rst +++ b/doc/guides/porting/shields.rst @@ -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{}; diff --git a/doc/reference/devicetree/api.rst b/doc/reference/devicetree/api.rst index 2ec2c3f098b..d81b67aac58 100644 --- a/doc/reference/devicetree/api.rst +++ b/doc/reference/devicetree/api.rst @@ -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"; diff --git a/doc/reference/storage/disk/access.rst b/doc/reference/storage/disk/access.rst index 66cb6110bc3..abf07fc56ab 100644 --- a/doc/reference/storage/disk/access.rst +++ b/doc/reference/storage/disk/access.rst @@ -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"; diff --git a/samples/basic/button/README.rst b/samples/basic/button/README.rst index 30c9658de66..762e223684b 100644 --- a/samples/basic/button/README.rst +++ b/samples/basic/button/README.rst @@ -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 { diff --git a/scripts/requirements-doc.txt b/scripts/requirements-doc.txt index 1b2e500416c..607db9ad2a5 100644 --- a/scripts/requirements-doc.txt +++ b/scripts/requirements-doc.txt @@ -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