ci: update documentation site

Publish documentation site without references
from the Handbook to the Getting Started Guide.

docs/_sources/getting-started.rst.txt

@@ -140,8 +140,6 @@ convenient but avoids installing anything in a development environment you actua
    pip install -U dtsh
 
 
-.. _dtsh-usage:
-
 Usage
 *****
 
@@ -176,8 +174,6 @@ We'll first confirm that the installation went well with a simple but typical us
 before tackling a few other scenarios.
 
 
-.. _dtsh-usage-default:
-
 Typical Use
 ===========
 
@@ -240,8 +236,6 @@ from the CMake cache content in ``CMakeCache.txt``::
      or if using West ``cd <project> && west build && dtsh``
 
 
-.. _dtsh-usage-others:
-
 Other Uses
 ==========
 
@@ -279,8 +273,6 @@ Where:
 - one of these directories shall contain a valid vendors file, e.g. ``dir1/vendor-prefixes.txt``
 
 
-.. _dtsh-usage-batch:
-
 Batch Mode
 ==========
 
@@ -320,8 +312,6 @@ following command:
    ❭
 
 
-.. _dtsh-configuration:
-
 Configuration
 *************
 

docs/_sources/handbook.rst.txt

@@ -3,9 +3,6 @@
 DTSh's Handbook
 ###############
 
-This handbook assumes you've already installed DTSh, and know how to open DTS files with ``dtsh``.
-If not, please go to the :ref:`dtsh-getting-started`.
-
 .. figure:: img/buses.png
   :align: center
   :alt: Buses
@@ -14,6 +11,223 @@ If not, please go to the :ref:`dtsh-getting-started`.
   ``find --on-bus * --OR --with-bus * -T --format NYCd``
 
 
+.. _dtsh-usage:
+
+Usage
+*****
+
+Once installed, the Devicetree Shell is available as the ``dtsh`` command:
+
+.. code-block:: none
+
+   $ dtsh -h
+   usage: dtsh [-h] [-b DIR] [-u] [--preferences FILE] [--theme FILE] [-c CMD] [-f FILE] [-i] [DTS]
+
+   shell-like interface with Devicetree
+
+   options:
+     -h, --help            show this help message and exit
+
+   open a DTS file:
+     -b DIR, --bindings DIR
+                           directory to search for binding files
+     DTS                   path to the DTS file
+
+   user files:
+     -u, --user-files      initialize per-user configuration files and exit
+     --preferences FILE    load additional preferences file
+     --theme FILE          load additional styles file
+
+   session control:
+     -c CMD                execute CMD at startup (may be repeated)
+     -f FILE               execute batch commands from FILE at startup
+     -i, --interactive     enter interactive loop after batch commands
+
+.. _dtsh-typical-use:
+
+Typical Use
+===========
+
+Early at build-time, during the `configuration phase <Zephyr-Configuration Phase_>`_,
+Zephyr *assembles* the final `devicetree <DTSpec-The Devicetree_>`_ that will represent
+the system hardware during the actual build phase.
+
+This devicetree is saved in `Devicetree Source Format <DTSpec-DTS_>`_ (DTS)
+in ``build/zephyr/zephyr.dts`` for *debugging* purpose.
+
+The typical DTSh's use case is to open this DTS file generated at build-time, e.g.:
+
+.. code-block:: none
+
+   $ cd zephyr/samples/sensor/bme680
+   $ cmake -B build -DBOARD=nrf52840dk_nrf52840
+   $ dtsh build/zephyr/zephyr.dts
+   dtsh (0.2.3): A Devicetree Shell
+   How to exit: q, or quit, or exit, or press Ctrl-D
+
+   /
+   > ls -l
+    Name              Labels          Binding
+    ───────────────────────────────────────────────────────
+    chosen
+    aliases
+    soc
+    pin-controller    pinctrl         nordic,nrf-pinctrl
+    entropy_bt_hci    rng_hci         zephyr,bt-hci-entropy
+    sw-pwm            sw_pwm          nordic,nrf-sw-pwm
+    cpus
+    leds                              gpio-leds
+    pwmleds                           pwm-leds
+    buttons                           gpio-keys
+    connector         arduino_header  arduino-header-r3
+    analog-connector  arduino_adc     arduino,uno-adc
+
+The above example should *always* work:
+
+- regardless of the installation method, ``cmake`` being sufficient for the configuration phase
+- regardless of whether ``ZEPHYR_BASE`` is set
+- regardless of whether you target a `supported board <Zephyr-Boards_>`_
+  or a `custom board <Zephyr-Board Porting Guide_>`_
+
+Here, DTSh retrieves *all it needs*, and especially where to search for the bindings files,
+from the CMake cache content in ``CMakeCache.txt``::
+
+   build/
+   ├── CMakeCache.txt
+   └── zephyr/
+       └── zephyr.dts
+
+.. tip::
+
+   - In this context, no need to pass the DTS file path to DTSh: by default it will try
+     to open the devicetree at ``build/zephyr/zephyr.dts``;
+     ``dtsh /path/to/project/build/zephyr/zephyr.dts`` would also work,
+     you don't need to call ``dtsh`` from the project's root
+   - To open *your* devicetree: ``cd <project> && cmake -B build -DBOARD=<board> && dtsh``,
+     or if using West ``cd <project> && west build && dtsh``
+
+
+.. _dtsh-other-uses:
+
+Other Uses
+==========
+
+As we've seen, DTSh first tries to retrieve the bindings Zephyr has used at build-time,
+when the DTS file was generated, from the CMake cache.
+This is the most straight forward way to get a complete and legit bindings search path.
+
+When this fails, DTSh will then try to work out the search path
+Zephyr would use if it were to generate the DTS *now*
+(`Where Bindings Are Located <Zephyr-Where Bindings Are Located_>`_): bindings found in
+``$ZEPHYR_BASE/dts/bindings`` and other *default* directories should still cover
+the most simple use cases (e.g. Zephyr samples).
+
+.. code-block:: none
+
+   $ export ZEPHYR_BASE=/path/to/zephyrproject/zephyr
+   $ dtsh /path/to/zephyr.dts
+
+This default behavior does not address all situations, though:
+
+- you may need additional bindings files from a custom location,
+  or explicitly set the ``DTS_ROOT`` CMake variable
+- you're not working with Zephyr
+
+For these use cases, the ``-b --bindings`` option permits to explicitly enumerate all the directories
+to search in:
+
+   $ dtsh --bindings dir1 --bindings dir2 foobar.dts
+
+Where:
+
+- ``dir1`` and ``dir1``, and their sub-directories, shall contain all necessary YAML binding files
+  in Zephyr's `Devicetree Binding Syntax <Zephyr-Binding Syntax_>`_,
+  even if not working with Zephyr
+- one of these directories shall contain a valid vendors file, e.g. ``dir1/vendor-prefixes.txt``
+
+
+.. _dtsh-configuration:
+
+Configuration
+=============
+
+Users can tweak DTSh appearance and behavior by overriding its defaults in configuration files:
+
+- ``dtsh.ini``: to override global preferences (see :ref:`dtsh-preferences`)
+- ``theme.ini``: to override styles and colors (see :ref:`dtsh-themes`)
+
+These (optional) files must be located in a platform-dependent directory,
+e.g. ``~/.config/dtsh`` on GNU/Linux systems.
+
+Running ``dtsh`` with the ``-u --user-files`` option will initialize configuration templates
+in the expected location:
+
+.. code-block:: none
+
+  $ dtsh -u
+  User preferences: ~/.config/dtsh/dtsh.ini
+  User theme: ~/.config/dtsh/theme.ini
+
+.. tip::
+
+   DTSh won't override a user file that already exists: manually remove the file(s),
+   and run the command again.
+
+Additionally:
+
+- the ``--preferences FILE`` option permits to specify an additional preferences file to load
+- the ``--theme FILE`` option permits to specify an additional theme file to load
+
+
+.. _dtsh-ini-format:
+
+Configuration Format
+--------------------
+
+Configuration files are simple INI files that contain key-value pairs.
+
+Values support *interpolation* with the ``${key}`` (preferences) or ``%(key)s`` (themes) syntax:
+
+.. code-block:: none
+
+   # Define a key.
+   wchar.ellipsis = \u2026
+
+   # Reference it with interpolation.
+   et_caetera = Et caetera${wchar.ellipsis}
+
+   # Use $$ to escape the dollar sign.
+   dollar = This is the dollar sign: $$
+
+Values are typed:
+
+String
+   Strings may contain Unicode characters as literals
+   or 4-digit hexadecimal code points.
+
+   It's necessary to double-quote strings only when:
+
+   - the string value actually ends with spaces
+   - the string value contains the double quote character
+
+   Leading and trailing double quotes are always striped.
+
+Boolean
+   Valid values (case-insensitive):
+
+   - True: ``1``, ``yes``, ``true``, and ``on``
+   - False: ``0``, ``no``, ``false``, and ``off``
+
+Integer
+   Integers in base-10, base-2 (prefix ``0b``), base-8 (prefix ``0o``),
+   and base-16 (prefix ``Ox``) are supported.
+
+   Prefixes are case insensitive.
+
+Float
+  Decimal (e.g. ``0.1``) and scientific (e.g. ``1e-1``) notations are supported.
+
+
 .. _dtsh-shell:
 
 The Shell
@@ -804,56 +1018,7 @@ Preferences are loaded in that order:
 3. if an additional preferences file is specified with the West command option ``--preferences``,
    it's eventually loaded, overriding previous values with the options it contains
 
-See also :ref:`dtsh-configuration` in the Getting Started Guide.
-
-
-.. _dtsh-ini-format:
-
-Configuration Format
---------------------
-
-DTSh is configured with simple INI files that contain key-value pairs.
-
-Values support *interpolation* with the ``${key}`` syntax:
-
-.. code-block:: none
-
-   # Define a key.
-   wchar.ellipsis = \u2026
-
-   # Reference it with interpolation.
-   et_caetera = Et caetera${wchar.ellipsis}
-
-   # Use $$ to escape the dollar sign.
-   dollar = This is the dollar sign: $$
-
-Values are typed:
-
-String
-   Strings may contain Unicode characters as literals
-   or 4-digit hexadecimal code points.
-
-   It's necessary to double-quote strings only when:
-
-   - the string value actually ends with spaces
-   - the string value contains the double quote character
-
-   Leading and trailing double quotes are always striped.
-
-Boolean
-   Valid values (case-insensitive):
-
-   - True: ``1``, ``yes``, ``true``, and ``on``
-   - False: ``0``, ``no``, ``false``, and ``off``
-
-Integer
-   Integers in base-10, base-2 (prefix ``0b``), base-8 (prefix ``0o``),
-   and base-16 (prefix ``Ox``) are supported.
-
-   Prefixes are case insensitive.
-
-Float
-  Decimal (e.g. ``0.1``) and scientific (e.g. ``1e-1``) notations are supported.
+See also :ref:`dtsh-configuration`.
 
 
 .. _dtsh-prefs-misc:
@@ -3185,7 +3350,7 @@ Styles are loaded in that order:
    it's eventually loaded, overriding previous styles
 
 Initialize a theme template with ``dtsh -u`` if not already done
-(see :ref:`dtsh-configuration` in the Getting Started Guide).
+(see :ref:`dtsh-configuration`).
 
 Comments in the template file should be sufficient to understand how to write styles,
 and identify which style applies to which type of information.

docs/getting-started.html

@@ -221,7 +221,7 @@
 </section>
 </section>
 <section id="usage">
-<span id="dtsh-usage"></span><h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
+<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
 <p>Once installed, the Devicetree Shell is available as the <code class="docutils literal notranslate"><span class="pre">dtsh</span></code> command:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ dtsh -h
 usage: dtsh [-h] [-b DIR] [-u] [--preferences FILE] [--theme FILE] [-c CMD] [-f FILE] [-i] [DTS]
@@ -250,7 +250,7 @@
 <p>We’ll first confirm that the installation went well with a simple but typical usage,
 before tackling a few other scenarios.</p>
 <section id="typical-use">
-<span id="dtsh-usage-default"></span><h3>Typical Use<a class="headerlink" href="#typical-use" title="Link to this heading"></a></h3>
+<h3>Typical Use<a class="headerlink" href="#typical-use" title="Link to this heading"></a></h3>
 <p>Early at build-time, during the <a class="reference external" href="https://docs.zephyrproject.org/latest/build/cmake/index.html#configuration-phase">configuration phase</a>,
 Zephyr <em>assembles</em> the final <a class="reference external" href="https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html">devicetree</a> that will represent
 the system hardware during the actual build phase.</p>
@@ -309,7 +309,7 @@
 </div>
 </section>
 <section id="other-uses">
-<span id="dtsh-usage-others"></span><h3>Other Uses<a class="headerlink" href="#other-uses" title="Link to this heading"></a></h3>
+<h3>Other Uses<a class="headerlink" href="#other-uses" title="Link to this heading"></a></h3>
 <p>As we’ve seen, DTSh first tries to retrieve the bindings Zephyr has used at build-time,
 when the DTS file was generated, from the CMake cache.
 This is the most straight forward way to get a complete and legit bindings search path.</p>
@@ -342,7 +342,7 @@
 </ul>
 </section>
 <section id="batch-mode">
-<span id="dtsh-usage-batch"></span><h3>Batch Mode<a class="headerlink" href="#batch-mode" title="Link to this heading"></a></h3>
+<h3>Batch Mode<a class="headerlink" href="#batch-mode" title="Link to this heading"></a></h3>
 <p>For scripting and automation, DTSh can also be used non-interactively by passing:</p>
 <blockquote>
 <div><ul class="simple">
@@ -380,7 +380,7 @@
 </section>
 </section>
 <section id="configuration">
-<span id="dtsh-configuration"></span><h2>Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h2>
+<h2>Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h2>
 <p>Users can tweak DTSh appearance and behavior by overriding its defaults in configuration files:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">dtsh.ini</span></code>: to override global preferences (see <a class="reference internal" href="handbook.html#dtsh-preferences"><span class="std std-ref">User Preferences</span></a>)</p></li>