From 3f8cc24dcc9943ff86bfb102128bc68bef412491 Mon Sep 17 00:00:00 2001 From: Daniel Barlow Date: Wed, 10 Jul 2024 23:36:24 +0100 Subject: [PATCH] fix most doc warnings --- ci.nix | 6 +++--- devices/gl-mt300n-v2/default.nix | 2 +- devices/qemu-aarch64/default.nix | 2 +- doc/admin.rst | 2 ++ doc/conf.py | 6 +++--- doc/hardware.nix | 8 ++++++-- doc/modules.rst | 2 +- doc/outputs.rst | 2 +- doc/parse-options-outputs.fnl | 2 +- doc/tutorial.rst | 2 +- modules/outputs/kexecboot.nix | 3 +++ 11 files changed, 23 insertions(+), 14 deletions(-) diff --git a/ci.nix b/ci.nix index 147962c..b3745e1 100644 --- a/ci.nix +++ b/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-outputs.fnl > doc/outputs-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.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\"" \ diff --git a/devices/gl-mt300n-v2/default.nix b/devices/gl-mt300n-v2/default.nix index 9061d4d..da3fbba 100644 --- a/devices/gl-mt300n-v2/default.nix +++ b/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 , 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. diff --git a/devices/qemu-aarch64/default.nix b/devices/qemu-aarch64/default.nix index 3c73b55..2b0ba4e 100644 --- a/devices/qemu-aarch64/default.nix +++ b/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. ''; diff --git a/doc/admin.rst b/doc/admin.rst index 6afae13..6bb159a 100644 --- a/doc/admin.rst +++ b/doc/admin.rst @@ -274,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 ===================== diff --git a/doc/conf.py b/doc/conf.py index 94f1685..37153c8 100644 --- a/doc/conf.py +++ b/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'] diff --git a/doc/hardware.nix b/doc/hardware.nix index 5e7f569..0a13578 100644 --- a/doc/hardware.nix +++ b/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" '' diff --git a/doc/modules.rst b/doc/modules.rst index 8d29bba..5d1187e 100644 --- a/doc/modules.rst +++ b/doc/modules.rst @@ -1,4 +1,4 @@ Module options ############## -.. include:: modules-generated.rst +.. include:: modules-generated.inc.rst diff --git a/doc/outputs.rst b/doc/outputs.rst index 971da15..477a69a 100644 --- a/doc/outputs.rst +++ b/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 diff --git a/doc/parse-options-outputs.fnl b/doc/parse-options-outputs.fnl index 3738a40..5c77d50 100644 --- a/doc/parse-options-outputs.fnl +++ b/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"))) diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 9ff5aff..e563535 100644 --- a/doc/tutorial.rst +++ b/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 diff --git a/modules/outputs/kexecboot.nix b/modules/outputs/kexecboot.nix index f7e0f0e..768b883 100644 --- a/modules/outputs/kexecboot.nix +++ b/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 '';