think

THOUGHTS.txt

@@ -5373,3 +5373,22 @@ wwan0.link.dhcpc-log
 194.4.172.12.l2tp
 s6rc-fdholder
 s6rc-oneshot-runner
+
+Wed Jul 10 23:37:00 BST 2024
+
+I propose rewriting the admin section. Topics we need to cover
+
+* building liminix given a configuration
+* installing for the first time
+  - refer to hardware section to find which of the following apply
+  - installation from openwrt
+  - installation from boot monitor
+* upgrading
+  - when you have a writable filesystem
+  - using levitate
+* using the running system (services, logs)
+
+we also need to expunge all mention of kexec
+
+and mention the upgrade choices in the Configuration section so
+people don't build an unupgradable image and only find out later

ci.nix

@@ -59,15 +59,15 @@ let
           ];
           src = ./.;
           buildPhase = ''
-            cat ${json} | fennel --correlate doc/parse-options.fnl > doc/modules-generated.rst
+            cat ${json} | fennel --correlate doc/parse-options.fnl > doc/modules-generated.inc.rst
-            cat ${json} | fennel --correlate doc/parse-options-outputs.fnl     > doc/outputs-generated.rst
+            cat ${json} | fennel --correlate doc/parse-options-outputs.fnl     > doc/outputs-generated.inc.rst
             cp ${(import ./doc/hardware.nix)} doc/hardware.rst
             make -C doc html
           '';
           installPhase = ''
             mkdir -p $out/nix-support $out/share/doc/
             cd doc
-            cp *-generated.rst  $out
+            cp *-generated.inc.rst hardware.rst $out
             ln -s ${json} $out/options.json
             cp -a _build/html $out/share/doc/liminix
             echo "file source-dist \"$out/share/doc/liminix\"" \

devices/gl-mt300n-v2/default.nix

@@ -13,7 +13,7 @@
     GL.iNet GL-MT300N-v2
     ********************
 
-    The GL-MT300N-v2 "Mango" is is very similar to the :ref:`MT300A <GL.iNet GL-MT300A>, but is
+    The GL-MT300N-v2 "Mango" is is very similar to the :ref:`gl-mt300a`, but is
     based on the MT7628 chipset instead of MT7620.  It's also marginally cheaper
     and comes in a yellow case not a blue one.  Be sure your device is
     v2 not v1, which is a different animal and has only half as much RAM.

devices/qemu-aarch64/default.nix

@@ -19,7 +19,7 @@
     ARM targets differ from MIPS in that the kernel format expected
     by QEMU is an "Image" (raw binary file) rather than an ELF
     file, but this is taken care of by :command:`run.sh`. Check the
-    documentation for the :ref:`QEMU` (MIPS) target for more information.
+    documentation for the :ref:`qemu` target for more information.
 
   '';
 

doc/admin.rst

@@ -42,7 +42,7 @@ in a particular piece of hardware) so you probably don't want to be
 starting them by hand if the conditions aren't there.
 
 A service may be **up** or **down** (there are no intermediate states
-like "started" or "stopping" or "dying" or "cogitating"). . Some (but
+like "started" or "stopping" or "dying" or "cogitating"). Some (but
 not all) services have "readiness" notifications: the dependents of a
 service with a readiness notification won't be started until the
 service signals (by writing to a nominated file descriptor) that it's
@@ -56,13 +56,14 @@ automatically. Liminix does not automatically set it to **down**.
 
 (If the process providing a service dies without ever notifying
 readiness, Liminix will restart it as many times as it has to until the
-timeout period elapses, and then stop it and mark it down.
+timeout period elapses, and then stop it and mark it down.)
 
 Controlled services
 ===================
 
 **Controlled** services are those which are started/stopped on demand
-by a controller instead of being started at boot time.  For example
+by a **controller** (another service) instead of being started at boot
+time.  For example:
 
 * ``svc.uevent-rule.build`` creates a controlled service which is
   active when a particular hardware device (identified by uevent/sysfs
@@ -273,6 +274,8 @@ Note that this only copies the package to the device: it doesn't update
 any profile to add it to ``$PATH``
 
 
+.. _rebuilding the system:
+
 Rebuilding the system
 =====================
 

doc/conf.py

@@ -7,19 +7,19 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Liminix'
-copyright = '2023, Daniel Barlow'
+copyright = '2023-2024 Daniel Barlow'
 author = 'Daniel Barlow'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx.ext.autosectionlabel'
+#    'sphinx.ext.autosectionlabel'
 ]
 autosectionlabel_prefix_document = True
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['*.inc.rst', '_build', 'Thumbs.db', '.DS_Store']
 
 
 

doc/hardware.nix

@@ -7,11 +7,15 @@ let
     n:
     let
       d = import ../devices/${n}/default.nix;
+      tag = ".. _${lib.strings.replaceStrings [" "] ["-"] n}:";
       d' = {
-        description = "${n}\n${substring 0 (stringLength n) "********************************"}\n";
+        description = ''
+          ${n}
+          ${substring 0 (stringLength n) "********************************"}
+        '';
       } // d;
     in
-    d'.description
+      "${tag}\n\n${d'.description}"
   ) devices;
 in
 writeText "hwdoc" ''

doc/modules.rst

@@ -1,4 +1,4 @@
 Module options
 ##############
 
-.. include:: modules-generated.rst
+.. include:: modules-generated.inc.rst

doc/outputs.rst

@@ -10,4 +10,4 @@ different artefacts, or have different ways to get that artefact
 installed. The options available for a particular device are described in
 the section for that device.
 
-.. include:: outputs-generated.rst
+.. include:: outputs-generated.inc.rst

doc/parse-options-outputs.fnl

@@ -16,4 +16,4 @@
 (each [_ option (ipairs (sorted-options (yaml.load (io.read "*a"))))]
   (when (and (output? option) (not option.internal))
     (print (.. ".. _" (string.gsub option.name "%." "-") ":") "\n")
-    (print option.description)))
+    (print option.description "\n")))

doc/tutorial.rst

@@ -300,7 +300,7 @@ machine, which for a test/demo system might involve a second network
 device in your build system - USB ethernet adapters are cheap - or
 a bit of messing around unplugging cables.)
 
-For more information about :code:`liminix-rebuild`, see the manual section :ref:`admin:Rebuilding the system`.
+For more information about :code:`liminix-rebuild`, see the manual section :ref:`Rebuilding the system`.
 
 
 Final thoughts

modules/outputs/kexecboot.nix

@@ -12,6 +12,9 @@ in {
     kexecboot = mkOption {
       type = types.package;
       description = ''
+        kexecboot
+        *********
+
         Directory containing files needed for kexec booting.
         Can be copied onto the target device using ssh or similar
       '';