From f60e9eac857bbc020c6f4c263f558c6ded8965f8 Mon Sep 17 00:00:00 2001 From: pennae Date: Mon, 2 Jan 2023 22:19:14 +0100 Subject: [PATCH] nixos/oh-my-zsh: convert manual chapter to MD --- nixos/modules/programs/zsh/oh-my-zsh.md | 109 +++++++++++ nixos/modules/programs/zsh/oh-my-zsh.nix | 2 + nixos/modules/programs/zsh/oh-my-zsh.xml | 227 +++++++++++------------ 3 files changed, 223 insertions(+), 115 deletions(-) create mode 100644 nixos/modules/programs/zsh/oh-my-zsh.md diff --git a/nixos/modules/programs/zsh/oh-my-zsh.md b/nixos/modules/programs/zsh/oh-my-zsh.md new file mode 100644 index 000000000000..73d425244ce7 --- /dev/null +++ b/nixos/modules/programs/zsh/oh-my-zsh.md @@ -0,0 +1,109 @@ +# Oh my ZSH {#module-programs-zsh-ohmyzsh} + +[`oh-my-zsh`](https://ohmyz.sh/) is a framework to manage your [ZSH](https://www.zsh.org/) +configuration including completion scripts for several CLI tools or custom +prompt themes. + +## Basic usage {#module-programs-oh-my-zsh-usage} + +The module uses the `oh-my-zsh` package with all available +features. The initial setup using Nix expressions is fairly similar to the +configuration format of `oh-my-zsh`. +``` +{ + programs.zsh.ohMyZsh = { + enable = true; + plugins = [ "git" "python" "man" ]; + theme = "agnoster"; + }; +} +``` +For a detailed explanation of these arguments please refer to the +[`oh-my-zsh` docs](https://github.com/robbyrussell/oh-my-zsh/wiki). + +The expression generates the needed configuration and writes it into your +`/etc/zshrc`. + +## Custom additions {#module-programs-oh-my-zsh-additions} + +Sometimes third-party or custom scripts such as a modified theme may be +needed. `oh-my-zsh` provides the +[`ZSH_CUSTOM`](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals) +environment variable for this which points to a directory with additional +scripts. + +The module can do this as well: +``` +{ + programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts"; +} +``` + +## Custom environments {#module-programs-oh-my-zsh-environments} + +There are several extensions for `oh-my-zsh` packaged in +`nixpkgs`. One of them is +[nix-zsh-completions](https://github.com/spwhitt/nix-zsh-completions) +which bundles completion scripts and a plugin for `oh-my-zsh`. + +Rather than using a single mutable path for `ZSH_CUSTOM`, +it's also possible to generate this path from a list of Nix packages: +``` +{ pkgs, ... }: +{ + programs.zsh.ohMyZsh.customPkgs = [ + pkgs.nix-zsh-completions + # and even more... + ]; +} +``` +Internally a single store path will be created using +`buildEnv`. Please refer to the docs of +[`buildEnv`](https://nixos.org/nixpkgs/manual/#sec-building-environment) +for further reference. + +*Please keep in mind that this is not compatible with +`programs.zsh.ohMyZsh.custom` as it requires an immutable +store path while `custom` shall remain mutable! An +evaluation failure will be thrown if both `custom` and +`customPkgs` are set.* + +## Package your own customizations {#module-programs-oh-my-zsh-packaging-customizations} + +If third-party customizations (e.g. new themes) are supposed to be added to +`oh-my-zsh` there are several pitfalls to keep in mind: + + - To comply with the default structure of `ZSH` the entire + output needs to be written to `$out/share/zsh.` + + - Completion scripts are supposed to be stored at + `$out/share/zsh/site-functions`. This directory is part of the + [`fpath`](http://zsh.sourceforge.net/Doc/Release/Functions.html) + and the package should be compatible with pure `ZSH` + setups. The module will automatically link the contents of + `site-functions` to completions directory in the proper + store path. + + - The `plugins` directory needs the structure + `pluginname/pluginname.plugin.zsh` as structured in the + [upstream repo.](https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins) + +A derivation for `oh-my-zsh` may look like this: +``` +{ stdenv, fetchFromGitHub }: + +stdenv.mkDerivation rec { + name = "exemplary-zsh-customization-${version}"; + version = "1.0.0"; + src = fetchFromGitHub { + # path to the upstream repository + }; + + dontBuild = true; + installPhase = '' + mkdir -p $out/share/zsh/site-functions + cp {themes,plugins} $out/share/zsh + cp completions $out/share/zsh/site-functions + ''; +} +``` diff --git a/nixos/modules/programs/zsh/oh-my-zsh.nix b/nixos/modules/programs/zsh/oh-my-zsh.nix index 41ea31b0f122..88b293bdfc62 100644 --- a/nixos/modules/programs/zsh/oh-my-zsh.nix +++ b/nixos/modules/programs/zsh/oh-my-zsh.nix @@ -142,5 +142,7 @@ in }; + # Don't edit the docbook xml directly, edit the md and generate it: + # `pandoc oh-my-zsh.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > oh-my-zsh.xml` meta.doc = ./oh-my-zsh.xml; } diff --git a/nixos/modules/programs/zsh/oh-my-zsh.xml b/nixos/modules/programs/zsh/oh-my-zsh.xml index 9917dd022b9f..c20659e83ccd 100644 --- a/nixos/modules/programs/zsh/oh-my-zsh.xml +++ b/nixos/modules/programs/zsh/oh-my-zsh.xml @@ -1,76 +1,72 @@ - - Oh my ZSH - - oh-my-zsh is a - framework to manage your ZSH - configuration including completion scripts for several CLI tools or custom - prompt themes. - -
- Basic usage - + + Oh my ZSH - The module uses the oh-my-zsh package with all available - features. The initial setup using Nix expressions is fairly similar to the - configuration format of oh-my-zsh. - + oh-my-zsh + is a framework to manage your + ZSH configuration + including completion scripts for several CLI tools or custom prompt + themes. + +
+ Basic usage + + The module uses the oh-my-zsh package with all + available features. The initial setup using Nix expressions is + fairly similar to the configuration format of + oh-my-zsh. + + { programs.zsh.ohMyZsh = { enable = true; - plugins = [ "git" "python" "man" ]; - theme = "agnoster"; + plugins = [ "git" "python" "man" ]; + theme = "agnoster"; }; } - For a detailed explanation of these arguments please refer to the - oh-my-zsh - docs. - - - - The expression generates the needed configuration and writes it into your - /etc/zshrc. - -
-
- Custom additions - - - Sometimes third-party or custom scripts such as a modified theme may be - needed. oh-my-zsh provides the - ZSH_CUSTOM - environment variable for this which points to a directory with additional - scripts. - - - - The module can do this as well: - + + For a detailed explanation of these arguments please refer to the + oh-my-zsh + docs. + + + The expression generates the needed configuration and writes it + into your /etc/zshrc. + +
+
+ Custom additions + + Sometimes third-party or custom scripts such as a modified theme + may be needed. oh-my-zsh provides the + ZSH_CUSTOM + environment variable for this which points to a directory with + additional scripts. + + + The module can do this as well: + + { - programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts"; + programs.zsh.ohMyZsh.custom = "~/path/to/custom/scripts"; } - -
-
- Custom environments - - - There are several extensions for oh-my-zsh packaged in - nixpkgs. One of them is - nix-zsh-completions - which bundles completion scripts and a plugin for - oh-my-zsh. - - - - Rather than using a single mutable path for ZSH_CUSTOM, - it's also possible to generate this path from a list of Nix packages: - +
+
+ Custom environments + + There are several extensions for oh-my-zsh + packaged in nixpkgs. One of them is + nix-zsh-completions + which bundles completion scripts and a plugin for + oh-my-zsh. + + + Rather than using a single mutable path for + ZSH_CUSTOM, it's also possible to generate this + path from a list of Nix packages: + + { pkgs, ... }: { programs.zsh.ohMyZsh.customPkgs = [ @@ -79,65 +75,67 @@ ]; } - Internally a single store path will be created using - buildEnv. Please refer to the docs of - buildEnv - for further reference. - - - - Please keep in mind that this is not compatible with - programs.zsh.ohMyZsh.custom as it requires an immutable - store path while custom shall remain mutable! An - evaluation failure will be thrown if both custom and - customPkgs are set. - -
-
- Package your own customizations - - - If third-party customizations (e.g. new themes) are supposed to be added to - oh-my-zsh there are several pitfalls to keep in mind: - - - - - To comply with the default structure of ZSH the entire - output needs to be written to $out/share/zsh. + Internally a single store path will be created using + buildEnv. Please refer to the docs of + buildEnv + for further reference. - - - Completion scripts are supposed to be stored at - $out/share/zsh/site-functions. This directory is part - of the - fpath - and the package should be compatible with pure ZSH - setups. The module will automatically link the contents of - site-functions to completions directory in the proper - store path. + Please keep in mind that this is not compatible with + programs.zsh.ohMyZsh.custom as it requires an + immutable store path while custom shall remain + mutable! An evaluation failure will be thrown if both + custom and customPkgs are + set. - - +
+
+ Package your own customizations - The plugins directory needs the structure - pluginname/pluginname.plugin.zsh as structured in the - upstream - repo. + If third-party customizations (e.g. new themes) are supposed to be + added to oh-my-zsh there are several pitfalls + to keep in mind: - - - - - A derivation for oh-my-zsh may look like this: - + + + + To comply with the default structure of ZSH + the entire output needs to be written to + $out/share/zsh. + + + + + Completion scripts are supposed to be stored at + $out/share/zsh/site-functions. This + directory is part of the + fpath + and the package should be compatible with pure + ZSH setups. The module will automatically + link the contents of site-functions to + completions directory in the proper store path. + + + + + The plugins directory needs the structure + pluginname/pluginname.plugin.zsh as + structured in the + upstream + repo. + + + + + A derivation for oh-my-zsh may look like this: + + { stdenv, fetchFromGitHub }: stdenv.mkDerivation rec { - name = "exemplary-zsh-customization-${version}"; - version = "1.0.0"; + name = "exemplary-zsh-customization-${version}"; + version = "1.0.0"; src = fetchFromGitHub { # path to the upstream repository }; @@ -150,6 +148,5 @@ stdenv.mkDerivation rec { ''; } - -
+