From 449b8fcce13240cbbb69c9e78184b08aca193d1c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 5 Nov 2024 15:33:40 +0000 Subject: [PATCH] Deployed a43dbbe to main with MkDocs 1.6.1 and mike 1.2.0.dev0 --- main/contributing/code/index.html | 78 +++++++++++++++++-------------- main/search/search_index.json | 2 +- 2 files changed, 44 insertions(+), 36 deletions(-) diff --git a/main/contributing/code/index.html b/main/contributing/code/index.html index 42eae04..6be6910 100644 --- a/main/contributing/code/index.html +++ b/main/contributing/code/index.html @@ -824,7 +824,11 @@

Formatting

43 44 45 -46
{
+46
+47
+48
+49
+50
{
   pkgs,
   inputs,
   ...
@@ -832,44 +836,48 @@ 
Formatting

 inputs.treefmt-nix.lib.mkWrapper pkgs {
   projectRootFile = ".git/config";
 
-  programs = {
-    alejandra.enable = true;
-    deadnix.enable = true;
-    gofumpt.enable = true;
-    prettier.enable = true;
-    statix.enable = true;
-  };
-
-  settings = {
-    global.excludes = [
-      "LICENSE"
-      # unsupported extensions
-      "*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore}"
-    ];
-
-    formatter = {
-      deadnix = {
-        priority = 1;
-      };
-
-      statix = {
-        priority = 2;
+  programs =
+    {
+      alejandra.enable = true;
+      deadnix.enable = true;
+      gofumpt.enable = true;
+      prettier.enable = true;
+      statix.enable = true;
+    }
+    // pkgs.lib.optionalAttrs (pkgs.system != "riscv64-linux") {
+      shellcheck.enable = true;
+    };
+
+  settings = {
+    global.excludes = [
+      "LICENSE"
+      # unsupported extensions
+      "*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore}"
+    ];
+
+    formatter = {
+      deadnix = {
+        priority = 1;
       };
 
-      alejandra = {
-        priority = 3;
+      statix = {
+        priority = 2;
       };
 
-      prettier = {
-        options = [
-          "--tab-width"
-          "4"
-        ];
-        includes = ["*.{css,html,js,json,jsx,md,mdx,scss,ts,yaml}"];
-      };
-    };
-  };
-}
+      alejandra = {
+        priority = 3;
+      };
+
+      prettier = {
+        options = [
+          "--tab-width"
+          "4"
+        ];
+        includes = ["*.{css,html,js,json,jsx,md,mdx,scss,ts,yaml}"];
+      };
+    };
+  };
+}

Checks

Running nix flake check will build all the devshells and Nix packages, as well as check the formatting with treefmt diff --git a/main/search/search_index.json b/main/search/search_index.json index 34625d9..2210f94 100644 --- a/main/search/search_index.json +++ b/main/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"contributing/code/","title":"Code","text":""},{"location":"contributing/code/#pre-requisites","title":"Pre-requisites","text":"

You will need to have the following installed:

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.

"},{"location":"contributing/code/#go-development","title":"Go development","text":"

The default devshell is a modified version of the underlying Nix derivation for nixos-facter. As such, it provides all the necessary tooling and utilities for working on nixos-facter.

nix/devshells/default.nix
{\n  perSystem,\n  pkgs,\n  ...\n}:\nperSystem.self.nixos-facter.overrideAttrs (old: {\n  GOROOT = \"${old.go}/share/go\";\n  nativeBuildInputs =\n    old.nativeBuildInputs\n    ++ [\n      perSystem.gomod2nix.default\n      pkgs.enumer\n      pkgs.delve\n      pkgs.pprof\n      pkgs.gotools\n      pkgs.golangci-lint\n      pkgs.cobra-cli\n      pkgs.fx # json tui\n      perSystem.hwinfo.default\n    ];\n  shellHook = ''\n    # this is only needed for hermetic builds\n    unset GO_NO_VENDOR_CHECKS GOSUMDB GOPROXY GOFLAGS\n  '';\n})\n

Direnv should load this by default when entering the root of the repository.

For the most part, you should be able to develop normally as you would any other Go program.

Important

When you have completed making any changes and have tested it as you would any other Go program, it is important to ensure it works when run as a Nix package.

This can be done with nix run .# -- <args>, which will build the Nix derivation and execute the resultant nixos-facter binary.

"},{"location":"contributing/code/#formatting","title":"Formatting","text":"

We use treefmt and treefmt-nix to format the repository by running nix fmt from the root directory.

nix/formatter.nix
{\n  pkgs,\n  inputs,\n  ...\n}:\ninputs.treefmt-nix.lib.mkWrapper pkgs {\n  projectRootFile = \".git/config\";\n\n  programs = {\n    alejandra.enable = true;\n    deadnix.enable = true;\n    gofumpt.enable = true;\n    prettier.enable = true;\n    statix.enable = true;\n  };\n\n  settings = {\n    global.excludes = [\n      \"LICENSE\"\n      # unsupported extensions\n      \"*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore}\"\n    ];\n\n    formatter = {\n      deadnix = {\n        priority = 1;\n      };\n\n      statix = {\n        priority = 2;\n      };\n\n      alejandra = {\n        priority = 3;\n      };\n\n      prettier = {\n        options = [\n          \"--tab-width\"\n          \"4\"\n        ];\n        includes = [\"*.{css,html,js,json,jsx,md,mdx,scss,ts,yaml}\"];\n      };\n    };\n  };\n}\n
"},{"location":"contributing/code/#checks","title":"Checks","text":"

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 that have been configured.

"},{"location":"contributing/code/#documentation","title":"Documentation","text":"

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.

"},{"location":"contributing/docs/","title":"Documentation","text":"

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/devshells/docs.nix
{\n  pkgs,\n  perSystem,\n  ...\n}:\npkgs.mkShellNoCC {\n  packages = with pkgs;\n  # Pop an empty shell on systems that aren't supported by godoc\n    lib.optionals (perSystem.godoc ? default)\n    ([\n        perSystem.godoc.default\n        (pkgs.writeScriptBin \"gen-reference\" ''\n          out=\"./docs/content/reference/go_doc\"\n          godoc -c -o $out .\n        '')\n        (pkgs.writeScriptBin \"mkdocs\" ''\n          # generate reference docs first\n          gen-reference\n          # execute the underlying command\n          ${pkgs.mkdocs}/bin/mkdocs \"$@\"\n        '')\n      ]\n      ++ (with pkgs.python3Packages; [\n        mike\n        mkdocs-material\n      ]));\n}\n

The docs are based on MkDocs and the MkDocs Material theme. You will find its configuration and content in the following locations:

"},{"location":"contributing/docs/#serve-locally","title":"Serve locally","text":"

To serve the docs locally run mkdocs serve from the root of the repository:

\u276f mkdocs serve\nINFO    -  Building documentation...\nINFO    -  Cleaning site directory\nWARNING -  The following pages exist in the docs directory, but are not included in the \"nav\" configuration:\n             - index.md\nINFO    -  Documentation built in 0.26 seconds\nINFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'\nINFO    -  [16:22:36] Serving on http://127.0.0.1:8000/nixos-facter/\n
"},{"location":"contributing/docs/#versioning-publication","title":"Versioning & Publication","text":"

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.

There is a github workflow, .github/workflows/gh-pages.yml which is responsible for publishing the docs. It does the following:

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.

"},{"location":"getting-started/generate-report/","title":"Generate a report","text":"

To generate a report, you will need to have Nix installed on the target machine.

NixpkgsFlake 
sudo nix run nixpkgs#nixos-facter -- -o facter.json\n
sudo nix run \\\n  --option experimental-features \"nix-command flakes\" \\\n  --option extra-substituters https://numtide.cachix.org \\\n  --option extra-trusted-public-keys numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE= \\\n  github:numtide/nixos-facter -- -o facter.json\n

This will scan your system and produce a JSON-based report in a file named facter.json:

facter.json
{\n  \"version\": 2, // (1)!\n  \"system\": \"x86_64-linux\", // (2)!\n  \"virtualisation\": \"none\", // (3)!\n  \"hardware\": { // (4)!\n    \"bios\": { ... },\n    \"bluetooth\": [ ... ],\n    \"bridge\": [ ... ],\n    \"chip_card\": [ ... ] ,\n    \"cpu\": [ ... ],\n    \"disk\": [ ... ],\n    \"graphics_card\": [ ... ],\n    \"hub\": [ ... ],\n    \"keyboard\": [ ... ],\n    \"memory\": [ ... ],\n    \"monitor\": [ ... ],\n    \"mouse\": [ ... ],\n    \"network_controller\": [ ... ],\n    \"network_interface\": [ ... ],\n    \"sound\": [ ... ],\n    \"storage_controller\": [ ... ],\n    \"system\": [ ... ],\n    \"unknown\": [ ... ],\n    \"usb_controller\": [ ... ]\n  },\n  \"smbios\": { // (5)!\n    \"bios\": { ... },\n    \"board\": { ... },\n    \"cache\": [ ... ],\n    \"chassis\": { ... },\n    \"config\": { ... },\n    \"language\": { ... },\n    \"memory_array\": [ ... ],\n    \"memory_array_mapped_address\": [ ... ],\n    \"memory_device\": [ ... ],\n    \"memory_device_mapped_address\": [ ... ],\n    \"memory_error\": [ ... ],\n    \"onboard\": [ ... ],\n    \"port_connector\": [ ... ],\n    \"processor\": [ ... ],\n    \"slot\": [ ... ],\n    \"system\": { ... }\n  }\n}\n
  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.

Tip

To use this report in your NixOS configuration, have a look at NixOS Facter Modules.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"contributing/code/","title":"Code","text":""},{"location":"contributing/code/#pre-requisites","title":"Pre-requisites","text":"

You will need to have the following installed:

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.

"},{"location":"contributing/code/#go-development","title":"Go development","text":"

The default devshell is a modified version of the underlying Nix derivation for nixos-facter. As such, it provides all the necessary tooling and utilities for working on nixos-facter.

nix/devshells/default.nix
{\n  perSystem,\n  pkgs,\n  ...\n}:\nperSystem.self.nixos-facter.overrideAttrs (old: {\n  GOROOT = \"${old.go}/share/go\";\n  nativeBuildInputs =\n    old.nativeBuildInputs\n    ++ [\n      perSystem.gomod2nix.default\n      pkgs.enumer\n      pkgs.delve\n      pkgs.pprof\n      pkgs.gotools\n      pkgs.golangci-lint\n      pkgs.cobra-cli\n      pkgs.fx # json tui\n      perSystem.hwinfo.default\n    ];\n  shellHook = ''\n    # this is only needed for hermetic builds\n    unset GO_NO_VENDOR_CHECKS GOSUMDB GOPROXY GOFLAGS\n  '';\n})\n

Direnv should load this by default when entering the root of the repository.

For the most part, you should be able to develop normally as you would any other Go program.

Important

When you have completed making any changes and have tested it as you would any other Go program, it is important to ensure it works when run as a Nix package.

This can be done with nix run .# -- <args>, which will build the Nix derivation and execute the resultant nixos-facter binary.

"},{"location":"contributing/code/#formatting","title":"Formatting","text":"

We use treefmt and treefmt-nix to format the repository by running nix fmt from the root directory.

nix/formatter.nix
{\n  pkgs,\n  inputs,\n  ...\n}:\ninputs.treefmt-nix.lib.mkWrapper pkgs {\n  projectRootFile = \".git/config\";\n\n  programs =\n    {\n      alejandra.enable = true;\n      deadnix.enable = true;\n      gofumpt.enable = true;\n      prettier.enable = true;\n      statix.enable = true;\n    }\n    // pkgs.lib.optionalAttrs (pkgs.system != \"riscv64-linux\") {\n      shellcheck.enable = true;\n    };\n\n  settings = {\n    global.excludes = [\n      \"LICENSE\"\n      # unsupported extensions\n      \"*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore}\"\n    ];\n\n    formatter = {\n      deadnix = {\n        priority = 1;\n      };\n\n      statix = {\n        priority = 2;\n      };\n\n      alejandra = {\n        priority = 3;\n      };\n\n      prettier = {\n        options = [\n          \"--tab-width\"\n          \"4\"\n        ];\n        includes = [\"*.{css,html,js,json,jsx,md,mdx,scss,ts,yaml}\"];\n      };\n    };\n  };\n}\n
"},{"location":"contributing/code/#checks","title":"Checks","text":"

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 that have been configured.

"},{"location":"contributing/code/#documentation","title":"Documentation","text":"

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.

"},{"location":"contributing/docs/","title":"Documentation","text":"

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/devshells/docs.nix
{\n  pkgs,\n  perSystem,\n  ...\n}:\npkgs.mkShellNoCC {\n  packages = with pkgs;\n  # Pop an empty shell on systems that aren't supported by godoc\n    lib.optionals (perSystem.godoc ? default)\n    ([\n        perSystem.godoc.default\n        (pkgs.writeScriptBin \"gen-reference\" ''\n          out=\"./docs/content/reference/go_doc\"\n          godoc -c -o $out .\n        '')\n        (pkgs.writeScriptBin \"mkdocs\" ''\n          # generate reference docs first\n          gen-reference\n          # execute the underlying command\n          ${pkgs.mkdocs}/bin/mkdocs \"$@\"\n        '')\n      ]\n      ++ (with pkgs.python3Packages; [\n        mike\n        mkdocs-material\n      ]));\n}\n

The docs are based on MkDocs and the MkDocs Material theme. You will find its configuration and content in the following locations:

"},{"location":"contributing/docs/#serve-locally","title":"Serve locally","text":"

To serve the docs locally run mkdocs serve from the root of the repository:

\u276f mkdocs serve\nINFO    -  Building documentation...\nINFO    -  Cleaning site directory\nWARNING -  The following pages exist in the docs directory, but are not included in the \"nav\" configuration:\n             - index.md\nINFO    -  Documentation built in 0.26 seconds\nINFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'\nINFO    -  [16:22:36] Serving on http://127.0.0.1:8000/nixos-facter/\n
"},{"location":"contributing/docs/#versioning-publication","title":"Versioning & Publication","text":"

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.

There is a github workflow, .github/workflows/gh-pages.yml which is responsible for publishing the docs. It does the following:

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.

"},{"location":"getting-started/generate-report/","title":"Generate a report","text":"

To generate a report, you will need to have Nix installed on the target machine.

NixpkgsFlake 
sudo nix run nixpkgs#nixos-facter -- -o facter.json\n
sudo nix run \\\n  --option experimental-features \"nix-command flakes\" \\\n  --option extra-substituters https://numtide.cachix.org \\\n  --option extra-trusted-public-keys numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE= \\\n  github:numtide/nixos-facter -- -o facter.json\n

This will scan your system and produce a JSON-based report in a file named facter.json:

facter.json
{\n  \"version\": 2, // (1)!\n  \"system\": \"x86_64-linux\", // (2)!\n  \"virtualisation\": \"none\", // (3)!\n  \"hardware\": { // (4)!\n    \"bios\": { ... },\n    \"bluetooth\": [ ... ],\n    \"bridge\": [ ... ],\n    \"chip_card\": [ ... ] ,\n    \"cpu\": [ ... ],\n    \"disk\": [ ... ],\n    \"graphics_card\": [ ... ],\n    \"hub\": [ ... ],\n    \"keyboard\": [ ... ],\n    \"memory\": [ ... ],\n    \"monitor\": [ ... ],\n    \"mouse\": [ ... ],\n    \"network_controller\": [ ... ],\n    \"network_interface\": [ ... ],\n    \"sound\": [ ... ],\n    \"storage_controller\": [ ... ],\n    \"system\": [ ... ],\n    \"unknown\": [ ... ],\n    \"usb_controller\": [ ... ]\n  },\n  \"smbios\": { // (5)!\n    \"bios\": { ... },\n    \"board\": { ... },\n    \"cache\": [ ... ],\n    \"chassis\": { ... },\n    \"config\": { ... },\n    \"language\": { ... },\n    \"memory_array\": [ ... ],\n    \"memory_array_mapped_address\": [ ... ],\n    \"memory_device\": [ ... ],\n    \"memory_device_mapped_address\": [ ... ],\n    \"memory_error\": [ ... ],\n    \"onboard\": [ ... ],\n    \"port_connector\": [ ... ],\n    \"processor\": [ ... ],\n    \"slot\": [ ... ],\n    \"system\": { ... }\n  }\n}\n
  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.

Tip

To use this report in your NixOS configuration, have a look at NixOS Facter Modules.

"}]} \ No newline at end of file