Cross-references

Cross-referencing Nix objects

To cross-reference Nix objects, you can use these Sphinx roles:

See also

For a complete list of roles, see the Roles reference.

Example

See the {nix:option}`services.autobar.package` option,
which is {nix:pkg}`hello` by default.

You might also want to examine {nix:func}`exampleLib.myFunc`.

Renders:

See the services.autobar.package option, which is hello by default.

You might also want to examine exampleLib.myFunc.

Cross-reference modifiers

Like for other builtin Sphinx domains, you can use the ~ modifier to only keep the last element in the output.

Example

See the {nix:option}`~services.autobar.package` option,
which is {nix:pkg}`~scope."special name"` by default.

You might also want to examine {nix:func}`~exampleLib.myFunc`.

Renders:

See the package option, which is "special name" by default.

You might also want to examine myFunc.

For more information and other modifiers, see Sphinx’s Cross-references syntax.

Cross-referencing relative to a given module

If you are documenting a given NixOS module in Markdown, chances are you are going to reference lots of options from that module.

The nix:currentmodule enables you to resolve all cross-references relative to a given module, which saves characters to type, and may make reading easier.

Example

```{nix:currentmodule} services.autobar
```

The autobar module provides a {nix:option}`package` option.

Renders:

The autobar module provides a package option.

Note how we didn’t have to specify the full services.autobar.package name.

The nix:currentmodule directive applies to the rest of the document. To reset the current module, pass None as argument.

Example

```{nix:currentmodule} None
```

The autobar module provides a {nix:option}`services.autobar.package` option.

Renders:

The autobar module provides a services.autobar.package option.

Cross-referencing external Nix objects

You can also reference Nix objects from any external documentation that uses Sphinx and sphinxcontrib-nixdomain, by using the Intersphinx built-in Sphinx extension.

Important

This feature requires an internet connection. This means that you have to build your documentation outside of the Nix sandbox, as this is intentionally not reproducible.

Add the project you want to link to in the intersphinx_mapping configuration:

conf.py — Adding the external documentation to Intersphinx
intersphinx_mapping = {
    "nixdomain": ("https://sphinxcontrib-nixdomain.readthedocs.io/en/stable/", None),
    # Another example project using `sphinxcontrib-nixdomain`
    "epnix": ("https://epics-extensions.github.io/EPNix/dev/", None),
}

With this configuration, any cross-referenced object might resolve to these external documentation.

Example

See the {nix:func}`nixdomainLib.documentObjects`
and the {nix:pkg}`epnix.epics-base` package.

Renders:

Explicit target

To explicitly select which project to link, use the {external+project:role} syntax.

Example

See the {external+epnix:nix:option}`programs.phoebus-client.enable` option.

Renders:

Turning off automatic resolve

To turn off automatically resolving to an external project, set the intersphinx_disabled_reftypes option.