doc: develop: manifests: external: add dtsh

Introduce documentation for using dtsh (a Devicetree Shell)
as an external module in Zephyr.

This module installs a West extension.

See also RFC #59863.

Signed-off-by: Christophe Dufaza <[email protected]>

Author: dottspina

doc/develop/manifest/external/dtsh.rst

@@ -0,0 +1,105 @@
+.. _external_module_dtsh:
+
+dtsh
+#######################
+
+Introduction
+************
+
+`DTSh <DTSh-Handbook_>`_ is an interactive DTS file viewer with
+a shell-like command line interface:
+
+- easily *navigate* and *visualize* the devicetree
+- find nodes based on e.g. supported bus protocols, bindings, generated IRQs,
+  memory size, or keywords like "sensor" or "PWM"
+- redirect commands output to files (text, HTML, SVG)
+  to document hardware configurations or simply take notes
+- contextual auto-completion, commands history, semantic highlighting, user profiles
+- script-able (aka batch modes)
+
+This Zephyr module adds DTSh as a West extension to your Zephyr workspace.
+
+
+Usage with Zephyr
+*****************
+
+To install the DTSh module, you will need to define your own manifest file,
+or pull it in by adding a submanifest.
+
+E.g. assuming the same paths as in `Zephyr Getting Started Guide`_,
+create ``zephyrproject/zephyr/submanifests/dtsh.yaml`` with the following content:
+
+.. code-block:: yaml
+
+   manifest:
+     projects:
+       - name: dtsh
+         url: https://github.com/dottspina/dtsh.git
+         revision: zephyr
+         path: modules/tools/dtsh
+         west-commands: scripts/west-commands.yml
+
+
+Then update the workspace and install DTSh requirements:
+
+.. code-block:: sh
+
+   west update dtsh
+   west packages -m dtsh pip --install
+
+.. note::
+
+   ``west update dtsh`` will fetch all tags from the `DTSh project <DTSh-project_>`_: ignore them,
+   they don't point to versions of this Zephyr module, and are entirely irrelevant here.
+
+
+The West command
+*****************
+
+Once installed, this project/module should provide the ``west dtsh`` command.
+
+.. code-block:: none
+
+   $ west build
+   $ west dtsh
+   dtsh (0.2.5-zephyr): Shell-like interface with Devicetree
+   How to exit: q, or quit, or exit, or press Ctrl-D
+
+   /
+   > cd &flash_controller
+
+   /soc/flash-controller@4001e000
+   > find -E --also-known-as (image|storage).* --format NKd -T
+                                Also Known As               Description
+                                ───────────────────────────────────────────────────────────────────────────────────
+   flash-controller@4001e000    flash_controller            Nordic NVMC (Non-Volatile Memory Controller)
+   └── flash@0                  flash0                      Flash node
+       └── partitions                                       This binding is used to describe fixed partitions…
+           ├── partition@c000   image-0, slot0_partition    Each child node of the fixed-partitions node represents…
+           ├── partition@82000  image-1, slot1_partition    Each child node of the fixed-partitions node represents…
+           └── partition@f8000  storage, storage_partition  Each child node of the fixed-partitions node represents…
+
+
+For the full West command synopsis, run ``west dtsh -h``.
+
+.. note::
+
+   It's recommended to install the module to its default location, ``modules/tools/dtsh``.
+   Otherwise, be sure to set the ``ZEPHYR_BASE`` environment variable before running ``west dtsh``.
+
+
+Reference
+*********
+
+- `DTSh project <DTSh-project_>`_
+- `DTSh Handbook <DTSh-Handbook_>`_
+- `dtsh module <dtsh-module_>`_
+
+
+.. _DTSh-project: https://github.com/dottspina/dtsh
+
+.. _DTSh-Handbook: https://dottspina.github.io/dtsh/handbook.html
+
+.. _dtsh-module: https://github.com/dottspina/dtsh/tree/zephyr
+
+.. _Zephyr Getting Started Guide: https://docs.zephyrproject.org/latest/develop/getting_started/