diff --git a/lib/options.nix b/lib/options.nix index 164bd6248534..195ba79765e9 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -672,11 +672,30 @@ rec { is necessary for complex values, e.g. functions, or values that depend on other values or packages. + # Examples + :::{.example} + ## `literalExpression` usage example + + ```nix + llvmPackages = mkOption { + type = types.str; + description = '' + Version of llvm packages to use for + this module + ''; + example = literalExpression '' + llvmPackages = pkgs.llvmPackages_20; + ''; + }; + ``` + + ::: + # Inputs `text` - : 1\. Function argument + : The text to render as a Nix expression */ literalExpression = text: @@ -688,6 +707,49 @@ rec { inherit text; }; + /** + For use in the `defaultText` and `example` option attributes. Causes the + given string to be rendered verbatim in the documentation as a code + block with the language bassed on the provided input tag. + + If you wish to render Nix code, please see `literalExpression`. + + # Examples + :::{.example} + ## `literalCode` usage example + + ```nix + myPythonScript = mkOption { + type = types.str; + description = '' + Example python script used by a module + ''; + example = literalCode "python" '' + print("Hello world!") + ''; + }; + ``` + + ::: + + # Inputs + + `languageTag` + + : The language tag to use when producing the code block (i.e. `js`, `rs`, etc). + + `text` + + : The text to render as a Nix expression + */ + literalCode = + languageTag: text: + lib.literalMD '' + ```${languageTag} + ${text} + ``` + ''; + /** For use in the `defaultText` and `example` option attributes. Causes the given MD text to be inserted verbatim in the documentation, for when diff --git a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py index 75fbeadce1d0..9e337e6b1082 100644 --- a/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py +++ b/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/options.py @@ -97,7 +97,7 @@ class BaseConverter(Converter[md.TR], Generic[md.TR]): if lit := option_is(option, key, 'literalMD'): return [ self._render(f"*{key.capitalize()}:*\n{lit['text']}") ] elif lit := option_is(option, key, 'literalExpression'): - code = md_make_code(lit['text']) + code = md_make_code(lit['text'], info="nix") return [ self._render(f"*{key.capitalize()}:*\n{code}") ] elif key in option: raise Exception(f"{key} has unrecognized type", option[key])