From 165937d01ec18c80c6171fa44df054207efebe93 Mon Sep 17 00:00:00 2001
From: pacien <pacien.trangirard@pacien.net>
Date: Mon, 11 Jan 2021 01:28:22 +0100
Subject: [PATCH] doc/fish: document fish plugins packaging

---
 doc/builders/packages/fish.section.md | 50 +++++++++++++++++++++++++++
 doc/builders/packages/index.xml       |  1 +
 2 files changed, 51 insertions(+)
 create mode 100644 doc/builders/packages/fish.section.md

diff --git a/doc/builders/packages/fish.section.md b/doc/builders/packages/fish.section.md
new file mode 100644
index 000000000000..43956fc531bb
--- /dev/null
+++ b/doc/builders/packages/fish.section.md
@@ -0,0 +1,50 @@
+# Fish {#sec-fish}
+
+Fish is a "smart and user-friendly command line shell" with support for plugins.
+
+
+## Vendor Fish scripts {#sec-fish-vendor}
+
+Any package may ship its own Fish completions, configuration snippets, and
+functions. Those should be installed to
+`$out/share/fish/vendor_{completions,conf,functions}.d` respectively.
+
+When the `programs.fish.enable` and
+`programs.fish.vendor.{completions,config,functions}.enable` options from the
+NixOS Fish module are set to true, those paths are symlinked in the current
+system environment and automatically loaded by Fish.
+
+
+## Packaging Fish plugins {#sec-fish-plugins-pkg}
+
+While packages providing standalone executables belong to the top level,
+packages which have the sole purpose of extending Fish belong to the
+`fishPlugins` scope and should be registered in
+`pkgs/shells/fish/plugins/default.nix`.
+
+The `buildFishPlugin` utility function can be used to automatically copy Fish
+scripts from `$src/{completions,conf,conf.d,functions}` to the standard vendor
+installation paths. It also sets up the test environment so that the optional
+`checkPhase` is executed in a Fish shell with other already packaged plugins
+and package-local Fish functions specified in `checkPlugins` and
+`checkFunctionPath` respectively.
+
+See `pkgs/shells/fish/plugins/pure.nix` for an example of Fish plugin package
+using `buildFishPlugin` and running unit tests with the `fishtape` test runner.
+
+
+## Fish wrapper {#sec-fish-wrapper}
+
+The `wrapFish` package is a wrapper around Fish which can be used to create
+Fish shells initialised with some plugins as well as completions, configuration
+snippets and functions sourced from the given paths. This provides a convenient
+way to test Fish plugins and scripts without having to alter the environment.
+
+```nix
+wrapFish {
+  pluginPkgs = with fishPlugins; [ pure foreign-env ];
+  completionDirs = [];
+  functionDirs = [];
+  confDirs = [ "/path/to/some/fish/init/dir/" ];
+}
+```
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index 732560ec1992..ab335e24ff99 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -11,6 +11,7 @@
  <xi:include href="elm.xml" />
  <xi:include href="emacs.section.xml" />
  <xi:include href="firefox.section.xml" />
+ <xi:include href="fish.section.xml" />
  <xi:include href="ibus.xml" />
  <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.section.xml" />