Merge pull request #29 from numtide/feat/docs

feat/docs

.envrc

@@ -3,6 +3,7 @@ if ! has nix_direnv_version || ! nix_direnv_version 3.0.5; then
 fi
 
 watch_file devshell.nix
+watch_file dev/private.narHash
 
 use flake
 

.github/workflows/gh-pages.yml

@@ -0,0 +1,44 @@
+name: Deploy docs
+
+on:
+    push:
+        branches:
+            - main
+        tags:
+            - "v*"
+
+    # Allows you to run this workflow manually from the Actions tab
+    workflow_dispatch:
+
+jobs:
+    deploy:
+        runs-on: ubuntu-22.04
+        permissions:
+            contents: write
+        concurrency:
+            group: ${{ github.workflow }}
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+            - uses: cachix/install-nix-action@V27
+              with:
+                  extra_nix_config: |
+                      accept-flake-config = true
+                      experimental-features = nix-command flakes
+            - name: Configure Git user
+              run: |
+                  git config --local user.email "github-actions[bot]@users.noreply.github.com"
+                  git config --local user.name "github-actions[bot]"
+            - name: Deploy main
+              if: ${{ github.ref_name == 'main' }}
+              run: |
+                  nix develop .#docs --command bash -c "mike deploy -p main"
+            - name: Deploy version
+              if: startsWith(github.ref, 'refs/tags/v')
+              run: |
+                  REF_NAME=${{ github.ref_name }}
+                  MAJOR_MINOR=${REF_NAME%.*}
+                  # strip the leading v from the ref_name
+                  # update the latest alias          
+                  nix develop .#docs --command bash -c "mike deploy -p -u ${MAJOR_MINOR} latest"

.gitignore

@@ -2,4 +2,5 @@
 result*
 *.qcow2
 .data
-report.json
+report.json
+site

README.md

@@ -11,9 +11,12 @@ This is made possible by the hardware report provided by [NixOS Facter].
 
 By default, these modules enable or disable themselves based on detected hardware.
 
+For more information, see the [docs].
+
 [NixOS modules]: https://wiki.nixos.org/wiki/NixOS_modules
 [NixOS Facter]: https://github.com/numtide/nixos-facter
 [NixOS Hardware]: https://github.com/NixOS/nixos-hardware
+[docs]: https://numtide.github.io/nixos-facter-modules
 
 ## Getting started
 

devshell.nix

@@ -1 +1,10 @@
-{ pkgs, ... }: pkgs.mkShellNoCC { packages = [ pkgs.nix-unit ]; }
+{ pkgs, ... }:
+pkgs.mkShellNoCC {
+  packages = [
+    pkgs.nix-unit
+    (pkgs.writeScriptBin "update-dev-private-narHash" ''
+      nix flake lock ./dev/private
+      nix hash path ./dev/private | tr -d '\n' > ./dev/private.narHash
+    '')
+  ];
+}

docs.nix

@@ -0,0 +1,109 @@
+{
+  pkgs,
+  ...
+}:
+pkgs.mkShellNoCC {
+  packages =
+    let
+      inherit (pkgs) lib;
+
+      # Capture root so we can identify our store paths below
+      root = toString ./.;
+
+      snakeCase = with lib; replaceStrings upperChars (map (s: "_" + s) lowerChars);
+
+      # Eval Facter module
+      eval = lib.evalModules {
+        modules = [
+          # Load the root module
+          ./modules/nixos/facter.nix
+          {
+            # Disable checks so it doesn't complain about NixOS related options which aren't available
+            config._module.check = false;
+            # Use the basic vm's report
+            config.facter.reportPath = ./hosts/basic/report.json;
+          }
+        ];
+      };
+
+      # Convert `/nix/store/...` store paths in the option declarations into a repository link.
+      # NOTE: we point at the main branch, but for versioned docs this will be incorrect.
+      # It's still a good starting point though.
+      transformDeclaration =
+        decl:
+        let
+          declStr = toString decl;
+          subpath = lib.removePrefix "/" (lib.removePrefix root declStr);
+        in
+        assert lib.hasPrefix root declStr;
+        {
+          url = "https://github.com/numtide/nixos-facter-modules/blob/main/${subpath}";
+          name = subpath;
+        };
+
+      # Convert options into options doc, transforming declaration paths to point to the github repository.
+      nixosOptionsDoc =
+        _name: options:
+        pkgs.nixosOptionsDoc {
+          inherit options;
+          transformOptions =
+            opt:
+            opt
+            // {
+              declarations = map transformDeclaration opt.declarations;
+            };
+        };
+
+      # Take an options attr set and produce a markdown file.
+      mkMarkdown =
+        name: options:
+        let
+          optionsDoc = nixosOptionsDoc name options;
+        in
+        pkgs.runCommand "${name}-markdown" { } ''
+          mkdir $out
+          cat ${optionsDoc.optionsCommonMark} > $out/${snakeCase name}.md
+        '';
+
+      # Allows us to gather all options that are immediate children of `facter` and which have no child options.
+      # e.g. facter.reportPath, facter.report.
+      # For all other options we group them by the first immediate child of `facter`.
+      # e.g. facter.bluetooth, facter.boot and so on.
+      # This allows us to have a page for root facter options "facter.md", and a page each for the major sub modules.
+      facterOptionsFilter =
+        _:
+        {
+          loc ? [ ],
+          options ? [ ],
+          ...
+        }:
+        (lib.length loc) == 2 && ((lib.elemAt loc 0) == "facter") && (lib.length options) == 0;
+
+      otherOptionsFilter = n: v: !(facterOptionsFilter n v);
+
+      facterMarkdown = mkMarkdown "facter" (lib.filterAttrs facterOptionsFilter eval.options.facter);
+      otherMarkdown = lib.mapAttrsToList mkMarkdown (
+        lib.filterAttrs otherOptionsFilter eval.options.facter
+      );
+
+      optionsMarkdown = pkgs.symlinkJoin {
+        name = "facter-module-markdown";
+        paths = [ facterMarkdown ] ++ otherMarkdown;
+      };
+
+    in
+    with pkgs;
+    [
+      (pkgs.writeScriptBin "mkdocs" ''
+        # rsync in NixOS modules doc to avoid issues with symlinks being owned by root
+        rsync -aL --chmod=u+rw --delete-before ${optionsMarkdown}/ ./docs/content/reference/nixos_modules
+
+        # execute the underlying command
+        ${pkgs.mkdocs}/bin/mkdocs "$@"
+      '')
+    ]
+    ++ (with pkgs.python3Packages; [
+      mike
+      mkdocs-material
+    ]);
+}

docs/content/contributing/code.md

@@ -0,0 +1,41 @@
+# Code
+
+## Pre-requisites
+
+You will need to have the following installed:
+
+-   [Nix]
+-   [Direnv]
+
+!!! important
+
+    We use a [Flake]-based workflow. You can certainly develop for `nixos-facter` without Flakes and leverage
+    much of what is listed below, but it is left up to the reader to determine how to make that work.
+
+## Formatting
+
+We use [treefmt] and [treefmt-nix] to format the repository by running `nix fmt` from the root directory.
+
+```nix title="nix/formatter.nix"
+--8<-- "formatter.nix"
+```
+
+## Checks
+
+Running `nix flake check` will build all the devshells and Nix packages, as well as check the formatting with [treefmt]
+and any other [Flake checks](https://github.com/NixOS/nix/blob/master/src/nix/flake-check.md) that have been configured.
+
+## Documentation
+
+When making changes, it is **important** to add or update any relevant sections in the documentation within the same
+pull request.
+
+For more information see the [next section](./docs.md).
+
+[Nix]: https://nixos.org
+[Flake]: https://wiki.nixos.org/wiki/Flakes
+[Nix derivation]: https://nix.dev/manual/nix/2.18/language/derivations
+[Direnv]: https://direnv.net
+[devshell]: https://nix.dev/tutorials/first-steps/declarative-shell.html
+[treefmt]: https://treefmt.com
+[treefmt-nix]: https://github.com/numtide/treefmt-nix

docs/content/contributing/docs.md

@@ -0,0 +1,68 @@
+# Documentation
+
+There is a separate [devshell] called `docs` which is provided for working with the docs locally.
+
+It can be entered by running: `nix develop .#docs`
+
+```nix title="nix/devshells/docs.nix"
+--8<-- "docs.nix"
+```
+
+The docs are based on [MkDocs] and the [MkDocs Material] theme.
+You will find its configuration and content in the following locations:
+
+-   `mkdocs.yaml`
+-   `./docs`
+
+## Serve locally
+
+To serve the docs locally run `mkdocs serve` from the root of the repository:
+
+```console
+❯ mkdocs serve
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+WARNING -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
+             - index.md
+INFO    -  Documentation built in 0.26 seconds
+INFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'
+INFO    -  [16:22:36] Serving on http://127.0.0.1:8000/nixos-facter/
+```
+
+## Versioning & Publication
+
+Versioning of the docs is managed through [mike].
+
+It is responsible for managing the structure of the `gh-pages` branch in the repository, which [Github Pages] is
+configured to serve from.
+
+!!! note
+
+    More information about versioning with [MkDocs Material] and [mike] can be found [here](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/).
+
+There is a github workflow, `.github/workflows/gh-pages.yml` which is responsible for publishing the docs.
+It does the following:
+
+-   On merge to `main`, the docs version [main](https://numtide.github.io/nixos-facter/main/) is updated.
+-   When a new tag is created of the form `v.<major>.<minor>.<patch>` a docs version `v<major>.<minor>` is created and the
+    [latest](https://numtide.github.io/nixos-facter/latest) alias is updated to point to this.
+
+The idea is that users will land on the latest released version of the docs by default, with `main` being available if
+they wish to read about unreleased features and changes.
+
+To preview the versions locally you can use `mike serve` instead of `mkdocs serve`.
+
+!!! warning
+
+    Be sure to have fetched the latest changes for the `gh-pages` branch first.
+    This is especially important if you are using `mike` locally to make manual changes to the published site.
+
+[Nix]: https://nixos.org
+[Flake]: https://wiki.nixos.org/wiki/Flakes
+[Nix derivation]: https://nix.dev/manual/nix/2.18/language/derivations
+[Direnv]: https://direnv.net
+[devshell]: https://nix.dev/tutorials/first-steps/declarative-shell.html
+[MkDocs]: https://www.mkdocs.org/
+[MkDocs Material]: https://squidfunk.github.io/mkdocs-material/
+[Github Pages]: https://pages.github.com/
+[mike]: https://github.com/jimporter/mike

docs/content/getting-started/generate-report.md

@@ -0,0 +1,78 @@
+# Generate a report
+
+To generate a report, you will need to have [Nix] installed on the target machine.
+
+```shell
+sudo nix run \
+  --option experimental-features "nix-command flakes" \
+  --option extra-substituters https://numtide.cachix.org \
+  --option extra-trusted-public-keys numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE= \
+  github:numtide/nixos-facter -- -o facter.json
+```
+
+!!! note
+
+    In the near-future we will add [nixos-facter] to [nixpkgs]. Until then, we recommend using the [Numtide Binary Cache]
+    to avoid having to build everything from scratch.
+
+This will scan your system and produce a JSON-based report in a file named `facter.json`:
+
+```json title="facter.json"
+{
+  "version": 2, // (1)!
+  "system": "x86_64-linux", // (2)!
+  "virtualisation": "none", // (3)!
+  "hardware": { // (4)!
+    "bios": { ... },
+    "bluetooth": [ ... ],
+    "bridge": [ ... ],
+    "chip_card": [ ... ] ,
+    "cpu": [ ... ],
+    "disk": [ ... ],
+    "graphics_card": [ ... ],
+    "hub": [ ... ],
+    "keyboard": [ ... ],
+    "memory": [ ... ],
+    "monitor": [ ... ],
+    "mouse": [ ... ],
+    "network_controller": [ ... ],
+    "network_interface": [ ... ],
+    "sound": [ ... ],
+    "storage_controller": [ ... ],
+    "system": [ ... ],
+    "unknown": [ ... ],
+    "usb_controller": [ ... ]
+  },
+  "smbios": { // (5)!
+    "bios": { ... },
+    "board": { ... },
+    "cache": [ ... ],
+    "chassis": { ... },
+    "config": { ... },
+    "language": { ... },
+    "memory_array": [ ... ],
+    "memory_array_mapped_address": [ ... ],
+    "memory_device": [ ... ],
+    "memory_device_mapped_address": [ ... ],
+    "memory_error": [ ... ],
+    "onboard": [ ... ],
+    "port_connector": [ ... ],
+    "processor": [ ... ],
+    "slot": [ ... ],
+    "system": { ... }
+  }
+}
+```
+
+1. Used to track major breaking changes in the report format.
+2. Architecture of the target machine.
+3. Indicates whether the report was generated inside a virtualised environment, and if so, what type.
+4. All the various bits of hardware that could be detected.
+5. [System Management BIOS] information if available.
+
+[Nix]: https://nixos.org
+[Numtide]: https://numtide.com
+[Numtide Binary Cache]: https://numtide.cachix.org
+[nixos-facter]: https://github.com/numtide/nixos-facter
+[nixpkgs]: https://github.com/nixos/nixpkgs
+[System Management BIOS]: https://wiki.osdev.org/System_Management_BIOS