feat(hakurei): docs

ci/docs.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -eu
+
+docs_try() {
+	local CMD=$1
+	shift
+
+	if type -P "$CMD" > /dev/null 2>&1; then
+		exec "$CMD" "$NF_DOCS_PATH/index.html" "$@"
+	fi
+}
+
+docs_try xdg-open "$@"
+docs_try open "$@"
+docs_try firefox "$@"
+docs_try chrome "$@"

devShells.nix

@@ -48,6 +48,7 @@
       nf-actions-test
       nf-update
       nf-tf
+      (mkWrapper {name = "nf-docs";})
       (mkWrapper {name = "nf-generate";})
       (mkWrapper {name = "nf-setup-node";})
       (mkWrapper {name = "nf-sops-keyscan";})

docs/_inc/attrs.adoc

@@ -0,0 +1,2 @@
+:source-highlighter: highlight.js
+:empty:

docs/derivation.nix

@@ -0,0 +1,37 @@
+{
+  lib,
+  asciidoctor,
+  stdenvNoCC,
+  self,
+}: let
+  inherit (lib.strings) hasSuffix;
+  src = lib.cleanSourceWith {
+    name = "genso-docs-src";
+    src = ./.;
+    filter = path: type:
+      (hasSuffix ".adoc" path || baseNameOf path == "docinfo.html")
+      || type == "directory";
+  };
+in stdenvNoCC.mkDerivation {
+  pname = "genso-docs";
+  version = "dev";
+  inherit src;
+
+  ASCIIDOCTOR_OPTS = [
+    "-a" "docinfo=shared"
+  ];
+
+  nativeBuildInputs = [ asciidoctor ];
+  passAsFile = [ "buildCommand" ];
+  buildCommand = ''
+    install -d "$out"
+    ASCIIDOCTOR_SRCS=(
+      $(find "$src" -type f -name '*.adoc' -not -path "$src/inc/*")
+    )
+    asciidoctor \
+      $ASCIIDOCTOR_OPTS \
+      -a docinfodir="$src/" \
+      -a inc="$src/_inc/" \
+      -b html -R "$src" -D "$out" "''${ASCIIDOCTOR_SRCS[@]}"
+  '';
+}

docs/docinfo.html

@@ -0,0 +1,10 @@
+<style>
+.value {
+	font-size: 1.1em;
+}
+
+.hexvalue, .pathvalue {
+	font-family: "Droid Sans Mono","DejaVu Sans Mono",monospace;
+}
+
+</style>

docs/index.adoc

@@ -0,0 +1,24 @@
+= https://gensokyo.zone[gensokyo.zone] Documentation
+:inc: ./_inc/
+include::{inc}attrs.adoc[]
+
+Welcome to the Palace of the Earth Spirits!
+
+== Infrastructure
+
+Links::
+* https://github.com/gensokyo-zone/infrastructure[GitHub Repository]
+* https://github.com/gensokyo-zone/infrastructure#readme[README]
+
+== Uncategorized
+
+https://gensokyo.zone[Homepage]::
+Service listing
+
+<<./network.adoc#,Home Network>>::
+Local network subnets and IP address reservations
+
+<<./steam.adoc#,Steam>>::
+
+<<./steam.adoc#beatsaber,Beat Saber>>:::
+Individual user and game version profiles deployed over the network

docs/network.adoc

@@ -0,0 +1,56 @@
+= Home Network
+:inc: ./_inc/
+include::{inc}attrs.adoc[]
+:toc:
+
+== Reserved Subnets
+
+* `10.1.1.0/24`
+* `fd0a::/64` (SLAAC)
+
+== Reserved IPv4 Addresses
+
+router:: `10.1.1.1`
+gensokyo:: `10.1.1.4`
+eientei:: `10.1.1.5`
+
+shanghai:: `10.1.1.32`
+
+hourai:: `10.1.1.36`
+
+tewi:: `10.1.1.38`
+
+tei:: `10.1.1.39`
+reisen:: `10.1.1.40`
+hakurei:: `10.1.1.41`
+kuwubernetes:: `10.1.1.42`
+mediabox:: `10.1.1.44`
+reimu:: `10.1.1.45`
+idp:: `10.1.1.46`
+aya:: `10.1.1.47`
+
+nue:: `10.1.1.62`
+koishi:: `10.1.1.63`
+satorin:: `10.1.1.64`
+fire10:: `10.1.1.65`
+chromecast:: `10.1.1.66`
+
+outdoor-friend:: `10.1.1.81`
+bedroom-friend:: `10.1.1.82`
+bedroom-colour-strip:: `10.1.1.85`
+
+net_ac_9628:: `10.1.1.90`
+
+pinecube:: `10.1.1.97`
+
+DHCP:: `10.1.1.98` to `10.1.1.252`
+
+== Exposed Ports
+
+hakurei::
+* ^UDP:^[.value]##137##, ^UDP:^[.value]##138##, ^TCP:^[.value]##139##, ^TCP:^[.value]##445##
+* ^TCP:^[.value]##80##, ^TCP:^[.value]##443##
+* ^TCP:^[.value]##636##
+* ^TCP:^[.value]##41022##, ^TCP:^[.value]##62954##
+* ^UDP:^[.value]##41641##
+* ^UDP:^[.value]##5353##

docs/steam.adoc

@@ -0,0 +1,67 @@
+= Steam
+:inc: ./_inc/
+include::{inc}attrs.adoc[]
+:toc:
+
+== Setup
+
+Environment Variables::
+
+Advanced System Settings (System Properties -> Advanced) -> Environment Variables
+
+* `GENSO_SMB_HOST` = [.value]`smb.gensokyo.zone`
+* [[env_GENSO_SMB_SHARED_MOUNT]] `GENSO_SMB_SHARED_MOUNT` = [.value]`\\smb.gensokyo.zone\shared` or `X:` if mapped as a network drive (recommended)
+* `GENSO_STEAM_MACHINE` = [.value]`mypc` your computer's name goes here
+* [[env_GENSO_STEAM_LOCAL_DATA]] `GENSO_STEAM_LOCAL_DATA` = [.value]`+C:\Program Files\GensokyoZone+` or somewhere local to be used as scratch space
+* [[env_GENSO_STEAM_INSTALL]] `GENSO_STEAM_INSTALL` = [.value]`+C:\Program Files (x86)\Steam+` or wherever Steam is installed to
+
+[[beatsaber]]
+== Beat Saber
+
+=== Setup
+
+Environment Variables::
+
+* `GENSO_STEAM_LIBRARY_BS` = [.value]`+G:\SteamLibrary+` if Beat Saber is installed to a different disk than <<env_GENSO_STEAM_INSTALL,`%GENSO_STEAM_INSTALL%`>>
+
+The scripts to manage the Beat Saber install are found under <<env_GENSO_SMB_SHARED_MOUNT,[.pathvalue]#%GENSO_SMB_SHARED_MOUNT%\steam\bin#>>.
+It is recommended to create a shortcut to this folder for convenient access by holding Alt and dragging it onto your Windows desktop.
+
+[[beatsaber_Vanilla]]
+To start initial setup, an existing Beat Saber install must be moved to its new home under <<env_GENSO_STEAM_LOCAL_DATA,[.pathvalue]#%GENSO_STEAM_LOCAL_DATA%\Beat Saber\Vanilla#>> by running [.pathvalue]#beatsaber/setup.bat#.
+
+[source,bat]
+%GENSO_SMB_SHARED_MOUNT%\steam\bin\beatsaber\setup.bat
+
+=== Updates
+
+It is recommended that the Steam `Automatic Updates` setting is changed to "Only update this game when I launch it" under the game's right click `Properties` -> `Updates` to avoid issues later on.
+
+When Steam does need to update the game, the <<beatsaber_Vanilla,vanilla local install>> must be restored for it to successfully perform the update and then allow you to continue playing the game. This just requires running [.pathvalue]#beatsaber/local-vanilla# prior to clicking the "Update" button in Steam.
+
+[source,bat]
+%GENSO_SMB_SHARED_MOUNT%\steam\bin\beatsaber\local-vanilla.bat
+
+=== Play
+
+Before playing the game, you must first select your user and game version:
+
+[[beatsaber_UserVersion]]
+[source,bat]
+%GENSO_SMB_SHARED_MOUNT%\steam\bin\steam\arc.bat
+%GENSO_SMB_SHARED_MOUNT%\steam\bin\beatsaber\1_34_2.bat
+
+These will be saved as environment variables to be used the next time the game is launched.
+
+Now to prepare the game:
+
+[source,bat]
+%GENSO_SMB_SHARED_MOUNT%\steam\bin\beatsaber\mount.bat
+
+This will set up directory links for the <<beatsaber_UserVersion,user and version previously selected>>.
+The game can now be launched normally through steam.
+
+Alternatively, you can mount and launch the game in one convenient command:
+
+[source,bat]
+%GENSO_SMB_SHARED_MOUNT%\steam\bin\beatsaber\launch.bat

nixos/access/gensokyo.nix

@@ -8,8 +8,18 @@
   inherit (lib.modules) mkDefault;
 in {
   services.nginx.virtualHosts.${config.networking.domain} = {
-    locations."/" = {
+    locations = {
-      root = inputs.website.packages.${pkgs.system}.gensokyoZone;
+      "/" = {
+        root = inputs.website.packages.${pkgs.system}.gensokyoZone;
+      };
+      "/docs" = {
+        root = pkgs.linkFarm "genso-docs-wwwroot" [
+          {
+            name = "docs";
+            path = inputs.self.packages.${pkgs.system}.docs;
+          }
+        ];
+      };
     };
   };
 }

packages/default.nix

@@ -133,5 +133,13 @@
       export PATH=":{makeBinPath [ packages.nf-alejandra ]}:$PATH"
       source ${../ci/fmt-nix.sh}
     '';
+    nf-docs = pkgs.writeShellScriptBin "nf-docs" ''
+      ${exports}
+      export NF_DOCS_PATH=${packages.docs}
+      source ${../ci/docs.sh}
+    '';
+    docs = pkgs.callPackage ../docs/derivation.nix {
+      inherit (inputs) self;
+    };
   };
 in output

readme.md

@@ -1,5 +1,7 @@
 # gensokyo.zone's Infrastructure
 
+[![docs-badge][]][docs]
+
 Welcome to the Palace of the Earth Spirits!
 
 ## Contribution Guidelines
@@ -51,3 +53,6 @@ vim .sops.yaml
 ```shell
 nf-tarball ct
 ```
+
+[docs-badge]: https://img.shields.io/badge/API-docs-blue.svg?style=flat-square
+[docs]: https://gensokyo.zone/docs/