mirror of
https://github.com/ilyakooo0/nixpkgs.git
synced 2024-09-20 20:20:26 +03:00
nixpkgs/NixOS manuals: devmode feature
Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
This commit is contained in:
parent
a49d40a005
commit
a064709342
@ -23,6 +23,14 @@ $ nix-shell
|
|||||||
|
|
||||||
If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual.html`.
|
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}
|
## 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.
|
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
20
doc/shell.nix
Normal 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
|
||||||
|
];
|
||||||
|
}
|
@ -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`.
|
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**
|
**Contributing to the man pages**
|
||||||
|
|
||||||
The man pages are written in [DocBook] which is XML.
|
The man pages are written in [DocBook] which is XML.
|
||||||
|
20
nixos/doc/manual/shell.nix
Normal file
20
nixos/doc/manual/shell.nix
Normal 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
|
||||||
|
];
|
||||||
|
}
|
117
pkgs/tools/nix/web-devmode.nix
Normal file
117
pkgs/tools/nix/web-devmode.nix
Normal 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
|
Loading…
Reference in New Issue
Block a user