nixpkgs/NixOS manuals: devmode feature

Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
This commit is contained in:
Shahar "Dawn" Or 2023-07-12 18:50:47 +07:00
parent a49d40a005
commit a064709342
5 changed files with 167 additions and 0 deletions

View file

@ -23,6 +23,14 @@ $ nix-shell
If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
## devmode {#sec-contributing-devmode}
The shell in the manual source directory makes available a command, `devmode`.
It is a daemon, that:
1. watches the manual's source for changes and when they occur — rebuilds
2. HTTP serves the manual, injecting a script that triggers reload on changes
3. opens the manual in the default browser
## Syntax {#sec-contributing-markup}
As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect.

20
doc/shell.nix Normal file
View file

@ -0,0 +1,20 @@
let
pkgs = import ../. {
config = {};
overlays = [];
};
common = import ./common.nix;
inherit (common) outputPath indexPath;
web-devmode = import ../pkgs/tools/nix/web-devmode.nix {
inherit pkgs;
buildArgs = "./.";
open = "/${outputPath}/${indexPath}";
};
in
pkgs.mkShell {
packages = [
web-devmode
];
}

View file

@ -11,6 +11,8 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux
If the build succeeds, the manual will be in `./result/share/doc/nixos/index.html`.
There's also [a convenient development daemon](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-devmode).
**Contributing to the man pages**
The man pages are written in [DocBook] which is XML.

View file

@ -0,0 +1,20 @@
let
pkgs = import ../../.. {
config = {};
overlays = [];
};
common = import ./common.nix;
inherit (common) outputPath indexPath;
web-devmode = import ../../../pkgs/tools/nix/web-devmode.nix {
inherit pkgs;
buildArgs = "../../release.nix -A manualHTML.${builtins.currentSystem}";
open = "/${outputPath}/${indexPath}";
};
in
pkgs.mkShell {
packages = [
web-devmode
];
}

View file

@ -0,0 +1,117 @@
{
pkgs,
# arguments to `nix-build`, e.g. `"foo.nix -A bar"`
buildArgs,
# what path to open a browser at
open,
}: let
inherit (pkgs) lib;
error_page = pkgs.writeShellScriptBin "error_page" ''
echo "<!DOCTYPE html>
<html>
<head>
<style>
@media (prefers-color-scheme: dark) {
:root { filter: invert(100%); }
}
</style>
</head>
<body><pre>$1</pre></body>
</html>"
'';
# The following would have been simpler:
# 1. serve from `$serve`
# 2. pass each build a `--out-link $serve/result`
# But that way live-server does not seem to detect changes and therefore no
# auto-reloads occur.
# Instead, we copy the contents of each build to the `$serve` directory.
# Using rsync here, instead of `cp`, to get as close to an atomic
# directory copy operation as possible. `--delay-updates` should
# also go towards that.
build_and_copy = pkgs.writeShellScriptBin "build_and_copy" ''
set -euxo pipefail
set +e
stderr=$(2>&1 nix-build --out-link $out_link ${buildArgs})
exit_status=$?
set -e
if [ $exit_status -eq 0 ];
then
# setting permissions to be able to clean up
${lib.getBin pkgs.rsync}/bin/rsync \
--recursive \
--chmod=u=rwX \
--delete-before \
--delay-updates \
$out_link/ \
$serve/
else
set +x
${lib.getBin error_page}/bin/error_page "$stderr" > $error_page_absolute
set -x
${lib.getBin pkgs.findutils}/bin/find $serve \
-type f \
! -name $error_page_relative \
-delete
fi
'';
# https://watchexec.github.io/
watcher = pkgs.writeShellScriptBin "watcher" ''
set -euxo pipefail
${lib.getBin pkgs.watchexec}/bin/watchexec \
--shell=none \
--restart \
--print-events \
${lib.getBin build_and_copy}/bin/build_and_copy
'';
# A Rust alternative to live-server exists, but it was not in nixpkgs.
# `--no-css-inject`: without this it seems that only CSS is auto-reloaded.
# https://www.npmjs.com/package/live-server
server = pkgs.writeShellScriptBin "server" ''
set -euxo pipefail
${lib.getBin pkgs.nodePackages_latest.live-server}/bin/live-server \
--host=127.0.0.1 \
--verbose \
--no-css-inject \
--entry-file=$error_page_relative \
--open=${open} \
$serve
'';
devmode =
pkgs.writeShellScriptBin "devmode"
''
set -euxo pipefail
function handle_exit {
rm -rf "$tmpdir"
}
tmpdir=$(mktemp -d)
trap handle_exit EXIT
export out_link="$tmpdir/result"
export serve="$tmpdir/serve"
mkdir $serve
export error_page_relative=error.html
export error_page_absolute=$serve/$error_page_relative
${lib.getBin error_page}/bin/error_page "building " > $error_page_absolute
${lib.getBin pkgs.parallel}/bin/parallel \
--will-cite \
--line-buffer \
--tagstr '{/}' \
::: \
"${lib.getBin watcher}/bin/watcher" \
"${lib.getBin server}/bin/server"
'';
in
devmode