In reply to @rina/:matrix.org
i mainly use nix outside nixos, and much of my packaging experience is with C/C++ and cmake. maybe more documentation on dealing with cmake external projects would be useful too

There is a wealth of information here: https://nixos.wiki/wiki/C

Mostly written by @Mic92 in past years AFAIK. Would be great to have that closer to the code, because all of that is Nixpkgs material.

We still haven't really figured out how to organise troubleshooting tips and other guide-like material across the ecosystem though. The last state of affairs was that we converged on the idea that it should be a bit like what Johannes Kirschbauer @hsjobeki proposes for function documentation, but for guides: have a uniform format used across Nix, Nixpkgs, and NixOS, and present that in one place, annotated with tags and searchable. But that is a lot of "should", and will require thinking about the structure of the manuals, moving around lots of text, and building automation for presenting the result.

In reply to @johannes.kirschbauer:scs.ems.host
Since #280592 The documentation of ‚writeShellApplication’ is not closely connected to the source anymore. The doc-comment was replaced by an explicit markdown document. Which is fine but we should have a more distinct way of creating a reference to the document such that a doc-comment tool knows that the documentation exists but is located at a different place.
We actually will need some more of those „rediretcion-directives“. One task is to research if there are usable standards for that (i somehow doubt that) or to come up with a good solution on our own.

In reply to @fricklerhandwerk:matrix.org
With nixdoc taking shape, does anything speak against systematically moving that text into the code?

There's some top-level attribute rev being passed through to the manual rendering machinery, which is used to create the source links. It comes from flake.nix, but I just can't find where and how it's set.

Ideas?

There's some top-level attribute rev being passed through to the Nixpkgs manual rendering machinery, which is used to create the source links. It comes from flake.nix, but I just can't find where and how it's set.

Ideas?

In reply to @pennae:matrix.eno.space
set by the flake machinery because it's a git repo, probably

Hm no, at least I don't see how a flake would do that. An empty flake like this:

{
  outputs = { self, ... }: {
    foo = self;
  };
}

called with nix eval .#foo doesn't show a rev attribute.

In reply to @pennae:matrix.eno.space
set by the flake machinery because it's a git repo, probably

Hm no, at least I don't see how a flake would do that. An empty flake in a Git repo, like this:

{
  outputs = { self, ... }: {
    foo = self;
  };
}

called with nix eval .#foo doesn't show a rev attribute.