From d5026c2074557247d97d0b14fe0043579c30886e Mon Sep 17 00:00:00 2001
From: Arnout Engelen <arnout@bzzt.net>
Date: Thu, 4 Jan 2024 14:34:46 +0100
Subject: [PATCH] docs: add hardware recommendation

Also add infrastructure to also generate the supported hardware
page when building the docs locally
---
 .gitignore       | 1 +
 README.md        | 2 +-
 doc/Makefile     | 6 +++++-
 doc/hardware.nix | 9 +++++++++
 doc/tutorial.rst | 2 ++
 5 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index f86642b..c1aaccb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,4 @@ result-*
 _build
 *-secrets.nix
 examples/static-leases.nix
+/doc/hardware.rst
diff --git a/README.md b/README.md
index 6ecdc68..ab07350 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ functioning version, see [the CI system](https://build.liminix.org/jobset/limini
 Documentation is in the [doc](doc/) directory. You can build it
 by running
 
-    nix-shell -p sphinx --run "make -C doc html"
+    nix-shell -p sphinx --run "make -C doc hardware.rst html"
 
 Rendered documentation corresponding to the latest commit on `main`
 is published to [https://www.liminix.org/doc/](https://www.liminix.org/doc/)
diff --git a/doc/Makefile b/doc/Makefile
index d4bb2cb..23fb60e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -12,9 +12,13 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+hardware.rst: hardware.nix
+	@rm -f hardware.rst || true
+	@cp $$(nix-build hardware.nix) hardware.rst
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+html: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/hardware.nix b/doc/hardware.nix
index e3733e9..8199e8a 100644
--- a/doc/hardware.nix
+++ b/doc/hardware.nix
@@ -24,6 +24,15 @@ writeText "hwdoc" ''
   Supported hardware
   ##################
 
+  For development, the `GL.iNet GL-MT300A <https://www.gl-inet.com/products/gl-mt300a/>`_
+  is an attractive choice as it has a builtin "debrick" procedure in the
+  boot monitor and is also comparatively simple to
+  attach serial cables to (soldering not required), so it
+  is lower-risk than some devices.
+
+  For a more powerful device, something with an ath10k would be the safe bet,
+  or the Linksys E8450 which seems popular in the openwrt community.
+
   ${lib.concatStringsSep "\n\n" texts}
 
 ''
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 2422bb8..9ff5aff 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -138,6 +138,8 @@ unbrick if necessary.
 	     work here, but you accept the slightly greater bricking
 	     risk if it doesn't.
 
+See :doc:`hardware` for device support status.
+
 You may want to read and inwardly digest the Develoment Manual section
 :ref:`serial` when you start working with Liminix on real hardware. You
 won't *need* serial access for this example, assuming it works, but it