nixos/doc: Source links are broken, pointing at "release-19.09"

[gloaming]

Describe the bug
"Declared by" source links are broken in the NixOS manual's Appendix A. Configuration Options

To Reproduce
Run nixos-help
Click next to go to Appendix A
Click on a source link

Expected behavior
I should land at the appropriate link for my Nixpkgs version, e.g. https://github.com/NixOS/nixpkgs/blob/8746c77a383/nixos/modules/config/appstream.nix

Actual behaviour
I land at a broken link for "release-19.09" e.g.
https://github.com/NixOS/nixpkgs/blob/release-19.09/nixos/modules/config/appstream.nix

Metadata

 - system: `"x86_64-linux"`
 - host os: `Linux 5.2.8, NixOS, 19.09pre188690.8746c77a383 (Loris)`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.2.2`
 - channels(craig): `""`
 - channels(root): `"nixos-19.09pre188690.8746c77a383"`
 - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixos`

[FRidh]

I suppose those links were never made with unstable in mind, only releases.

[matthewbauer]

Yeah we don't really differentiate between released and unreleased. Those links just come from the revision field:

nixpkgs/doc/doc-support/lib-function-locations.nix

Line 60 in 86f3127

urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";

[gloaming]

It appears that it is supposed to be the git revision, but it's falling back:

nixpkgs/doc/doc-support/lib-function-locations.nix

Line 3 in 86f3127

revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");

nix-repl> lib.trivial.revisionWithDefault null
"3f6d0a981a56a55c47cdbdc5f44ddb0372d00909"

nixpkgs/lib/trivial.nix

Lines 151 to 160 in 86f3127

	revisionWithDefault =
	# Default value to return if revision can not be determined
	default:
	let
	revisionFile = "${toString ./..}/.git-revision";
	gitRepo = "${toString ./..}/.git";
	in if lib.pathIsDirectory gitRepo
	then lib.commitIdFromGitRepo gitRepo
	else if lib.pathExists revisionFile then lib.fileContents revisionFile
	else default;

$ cat /nix/var/nix/profiles/per-user/root/channels/nixos/.git-revision 
54c76638733ca5e85aefea3caefd3286e8b537c5

So why doesn't it work? 😕

[stale]

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
2. Ask on the NixOS Discourse.
3. Ask on the #nixos channel on irc.freenode.net.

[ncfavier]

There are two different things here:

• The revision used for the links to option declarations in the NixOS manual (what this issue is about AFAICT) is currently determined by lib.trivial.release, which points to the next release on the unstable branches, hence the broken links. This is fixed by the introduction of manualRevision in nixos/doc: render option values using lib.generators.toPretty #199363.
• The revision used for the links to the sources of library functions in the nixpkgs manual, which is determined by nixpkgs/doc/doc-support/lib-function-locations.nix. This doesn't seem too broken, except that it points to master even in the stable manual, so it should probably be made to use manualRevision as well.

[jtojnar]

The manual rendering has since been reimplemented. The new n-r-d toolchain supports linking to master but expects local as a revision to do that:

nixpkgs/pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/options.py

Lines 59 to 62 in 40066ba

	if self._revision == 'local':
	href = f"https://github.com/NixOS/nixpkgs/blob/master/{loc}"
	else:
	href = f"https://github.com/NixOS/nixpkgs/blob/{self._revision}/{loc}"

but that does not appear to be set anywhere.

Nixpkgs manual uses master instead:

nixpkgs/doc/default.nix

Line 137 in 87bc60c

--revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \

And NixOS manual receives it from argument to default.nix:

nixpkgs/nixos/doc/manual/default.nix

Line 125 in 87bc60c

--revision ${escapeShellArg revision} \

Which is set in the documentation module to a hardcoded version:

nixpkgs/nixos/modules/misc/documentation.nix

Line 57 in 6ee6ce8

revision = "release-${version}";

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/links-in-unstable-nixos-manual-appendix-are-broken/46395/3