From d5026c2074557247d97d0b14fe0043579c30886e Mon Sep 17 00:00:00 2001 From: Arnout Engelen 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 f86642b9..c1aaccbd 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 6ecdc68f..ab07350e 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 d4bb2cbb..23fb60e3 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 e3733e92..8199e8a5 100644 --- a/doc/hardware.nix +++ b/doc/hardware.nix @@ -24,6 +24,15 @@ writeText "hwdoc" '' Supported hardware ################## + For development, the `GL.iNet 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 2422bb86..9ff5aff5 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