Nix library¶

Main functions¶

nixdomainLib.documentObjects[source]¶

Document the given objects.

Type:

{ sources; options; packages; library; } -> store path

Parameters:

sources (attrSet of strings) – a source-name -> source-path attribute set. The source self is expected to be your project’s root path.
options (attrSet) – the set of options to document, forwarded to options.document. See its documentation for more information.
packages (attrSet) – the set of packages to document, forwarded to packages.document. See its documentation for more information.
library (attrSet) – the set of functions to document, forwarded to library.document. See its documentation for more information.

Returns:

a JSON file used by the sphinxcontrib-nixdomain Sphinx extension, to be passed through the NIXDOMAIN_OBJECTS environment variable.

Example usage¶

lib.documentObjects {
  sources = {
    self = inputs.self.outPath;
    nixpkgs = inputs.nixpkgs.outPath;
  };
  options = {
    options =
      (inputs.nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [ self.nixosModules.default ];
      }).options;
    extraFilters = [
      # Example filter: the option has a description
      (opt: opt ? description)
    ];
    packages.packages = inputs.self.packages.x86_64-linux;
    library = {
      # Choosing a name different than "lib" is recommended,
      # to avoid confusion with Nixpkgs' "lib"
      name = "myLib";
      library = inputs.self.lib;
    };
  };
}

Customize options¶

nixdomainLib.options.document[source]¶

Document the given options.

Tip

This function is called by nixdomainLib.documentObjects with its options attribute value. There is no need to call it directly, pass the arguments of this function to the options attribute of the nixdomainLib.documentObjects function.

Type:

{
  sources;
  options;
  filters;
  extraFilters;
  modifiers;
  extraModifiers;
} -> attrSet

Parameters:

sources (attrSet of strings) – see nixdomainLib.documentObjects.
options (attrSet of options) – the set of options to document, as returned by (lib.nixosSystem { ... }).options.
filters (list of (option -> bool) functions) – a list of function that filters the set of options to document. By default, keep only visible options that are declared in the self source.
extraFilters (list of (option -> bool) functions) – extra filters to apply in addition to filters.
modifiers (list of (option -> option) functions) – apply this list of function to each option. By default, make the option declarations relative to the given sources.
extraModifiers (list of (option -> option) functions) – extra modifiers to apply in addition to modifiers.

Returns:

an attribute set of options, usable by the sphinxcontrib-nixdomain Sphinx extension.

nixdomainLib.options.attrSetToDocList[source]¶

Generate documentation template from the list of option declaration like the set generated with filterOptionSets.

Originally taken from nixpkgs’ lib.optionAttrSetToDocList.

nixdomainLib.options.renderOptionValue[source]¶: Ensures that the given option value (default or example) is a string by rendering Nix values.

nixdomainLib.options.filters.isVisible[source]¶

Returns whether the given option should be visible in the documentation.

Type:: option :: option -> bool
Parameters:: option (option) – the option to check

nixdomainLib.options.filters.isDeclaredIn[source]¶

Returns whether the given option is declared in the given directory.

Type:

prefix :: string -> option :: option -> bool

Parameters:

prefix (string) – the directory where the option should be declared
option (option) – the option to check

nixdomainLib.options.modifiers.relativeDeclaration[source]¶

URLify the declarations of the given option.

Type:

sources :: attrSet -> option :: option -> bool

Parameters:

sources (attrSet of strings) – the available sources to replace
option (option) – the option whose declarations to change

Returns:

the modified option

Customize packages¶

nixdomainLib.packages.document[source]¶

Document the given packages.

Tip

This function is called by nixdomainLib.documentObjects with its packages attribute value. There is no need to call it directly, pass the arguments of this function to the packages attribute of the nixdomainLib.documentObjects function.

Type:

{
  sources;
  packages;
  filters;
  extraFilters;
  modifiers;
  extraModifiers;
  metaAttributes;
} -> attrSet

Parameters:

sources (attrSet of strings) – see nixdomainLib.documentObjects.
packages (attrSet of packages) – the set of packages to document. Follows the lib.recurseIntoAttrs indicator when recursing into children attribute sets.
filters (list of (package -> bool) functions) – a list of function that filters the set of packages to document. By default, no filter is applied.
extraFilters (list of (package -> bool) functions) – extra filters to apply in addition to filters.
modifiers (list of (package -> package) functions) – apply this list of function to each package. By default, make the package declaration relative to the given sources, and keep only the tier 1 and tier 2 platforms in platforms attribute.
extraModifiers (list of (package -> package) functions) – extra modifiers to apply in addition to modifiers.

Returns:

an attribute set of packages, usable by the sphinxcontrib-nixdomain Sphinx extension.

nixdomainLib.packages.tier1Platforms[source]¶

The list of Nixpkgs tier 1 platforms.

Type:: list of strings

nixdomainLib.packages.tier2Platforms[source]¶

The list of Nixpkgs tier 2 platforms.

Type:: list of strings

nixdomainLib.packages.collectPackage[source]¶

Collect information about a given package, with the given meta attributes.

Type:

metaAttrs :: list -> pkg :: package -> package

Parameters:

metaAttrs (list of str) – the meta attributes to collect for the given package
pkg (package) – the package to collect information from

nixdomainLib.packages.collect[source]¶

Collect all packages recursively, into an attribute set of loc -> derivation.

Respects Nixpkgs’s recurseIntoAttrs.

Inspired by flake-utils’ flattenTree.

Parameters:

metaAttrs (list of str) – the meta attributes to collect for each package
set (attribute set) – the set containing the packages to collect

nixdomainLib.packages.modifiers.relativePosition[source]¶

URLify the position of the given package.

Type:

sources :: attrSet -> pkg :: package -> package

Parameters:

sources (attrset of str) – the available sources to replace
pkg (package) – the package whose position to change

Returns:

the modified package

nixdomainLib.packages.modifiers.filterPlatforms[source]¶

Change the package’s declared platform to only show the given ones.

This function is useful to limit the shown platforms to only the supported ones.

Type:

shownPlatforms :: list -> pkg :: package -> package

Parameters:

shownPlatforms (list of str) – the platforms to show
pkg (package) – the package to change

Returns:

the modified package

Customize library¶

nixdomainLib.library.document[source]¶

Document the given functions.

Tip

This function is called by nixdomainLib.documentObjects with its library attribute value. There is no need to call it directly, pass the arguments of this function to the library attribute of the nixdomainLib.documentObjects function.

Type:

{ sources; library; name; } -> list

Parameters:

sources (attrSet of strings) – see nixdomainLib.documentObjects.
library (attrSet of functions) – the set of functions to document. Recurses into children attribute sets and ignores undocumented functions.
name (string) – The name/prefix of the library. Defaults to "lib".

Returns:

a list of nixdoc invocations to be run by nixdomainLib.documentObjects, which is then usable by the sphinxcontrib-nixdomain Sphinx extension.

Utilities¶

nixdomainLib.utils.pathToURL[source]¶

Convert a path that’s inside the Nix store to a URL to be passed to nixdomain_linkcode_resolve.

Parameters:

sources (attrset of str) – the available sources to replace
path (str) – the path whose prefix to replace

Returns:

the path with the prefix replaced