nix-flake: Fix and expand on 'getting started' documentation

Signed-off-by: Sarah Renkhoff <[email protected]>

doc/bridle/gs_nix.rst

@@ -7,52 +7,91 @@ Working with Bridle via Nix
    :local:
    :depth: 2
 
-An alternative way to develop with Bridle is through `Nix <https://nixos.org/>`_, a functional package
-managing system. This way, all dependencies can be installed using a single
-tool. Packages installed this way don't pollute your regular system, and can
-easily be removed later.
+An alternative way to develop with Bridle is through `Nix
+<https://nixos.org/>`_, a functional package managing system. This way, all
+dependencies can be installed using a single tool. Packages installed this way
+don't pollute your regular system, and can easily be removed later.
 
 Installing the Nix Package Manager
 **********************************
 
 To get started using Nix, you will need to install the package manager itself.
 Most distributions provide packages for installing it using their regular
 package manager (e.g. Ubuntu provides a ``nix`` package that can be installed
-using ``apt install nix``). If your distribution doesn't provide such a package, see the
-instructions on `nixos.org <https://nixos.org/download>` to get a Nix
+using ``apt install nix``). If your distribution doesn't provide such a package,
+see the instructions on `nixos.org <https://nixos.org/download>`_ to get a Nix
 installation.
 
 Enabling Flakes
 ***************
 
 Flakes are an experimental feature that enables fully hermetic and reproducible
-builds. To enable flakes, add
-
-.. parsed-literal::
-   :class: highlight
+builds. To enable flakes, add::
 
    experimental-features = nix-command flakes
 
-to ``~/.config/nix/nix.conf`` (creating this file if it doesn't exist).
+to your private Nix configuration in ``~/.config/nix/nix.conf`` (creating this
+file if it doesn't exist).
 
 Using the Bridle Flake
 **********************
 
 The Bridle flake provides a ``devShell`` output, which is a shell environment in
 which all necessary tools and dependencies are present for developing Zephyr
-applications with Bridle. By running `nix develop` within the bridle repository,
+applications with Bridle. By running ``nix develop`` within the bridle repository,
 you enter this environment. You can then proceed to create a west workspace
 ontop of your bridle directory and work as usual.
 
+You can also use the build hooks provided by the ``west2nix`` input to perform
+builds directly via Nix, without creating an explicit west workspace. In this
+case, the workspace manifest used will be that provided by the ``west2nix.toml``
+lockfile (see below on how to bring it up-to-date if required). For an example
+of such a derivation, see ``doc.nix``, which builds this documentation. For
+another example of a simpler build, see `the west2nix repository
+<https://github.com/adisbladis/west2nix>`_.
+
 Keeping the Bridle Flake Up-to-date
 ***********************************
 
 Like all nix flakes, the Bridle flake has its inputs locked using the
 ``flake.lock`` file. Running ``nix flake update`` in the bridle directory will
-check for upstream changes and bump any changed inputs in the lockfile.
+check for upstream changes and bump any changed inputs in the lockfile. After
+checking for breakages due to the update, e.g. via ``nix flake check``, and
+confirming that ``nix develop`` drops you into a working shell, you should can
+commit the updated ``flake.lock``. If you do notice breakage, you can simply
+revert the update with ``git checkout flake.lock``.
 
 The flake also relies on the manifest lockfile ``west2nix.toml``, which reflects
-the state of a west workspace at a specific time. To update this lockfile, the
-workspace you want to lock needs to be fully checked out. Within this workspace,
-run ``nix run bridle#west2nix`` to generate a new ``west2nix.toml``, which can
-then be placed in the bridle directory.
+the state of a west workspace at a specific time. To update this lockfile, you
+first need a full checkout of the workspace you want to lock:
+
+.. code-block:: console
+
+   mkdir workspace && cd workspace
+   git clone https://github.com/tiacsys/bridle.git
+   west init -l bridle
+   west update
+
+You can then run ``west2nix`` on this workspace and place the resulting lockfile
+into the ``bridle`` directory:
+
+.. code-block:: console
+
+   nix run ./bridle#west2nix
+   mv west2nix.toml bridle/
+
+.. note::
+
+   Running ``west2nix`` directly inside the ``bridle`` directory is
+   likely to fail due to permission issues, hence running it from the workspace
+   directory instead.
+
+Finally, you can commit your new lockfile:
+
+.. code-block:: console
+
+   git add west2nix.toml
+   git commit -m "Updated west2nix.toml"
+
+Similarly to updating the flake inputs, this update can be reverted simply by
+resetting ``west2nix.toml`` to an earlier state.