also updates nixdoc to 2.3.0. the nixdoc update is not a separate commit
because that would leave the manual build broken for one commit,
potentially breaking bisects and rebases.
This reverts commit 7e6c518ce4.
I misinterpreted Github's CI failure in the notification tab and
thought that I had broken CI on origin/master, so I panic-reverted
before I merged it (I thought they had).
On closer inspection, it appears that the CI failure was not from
the tip that I merged. This PR resubmits the reverted change. I'll
wait for OfBorg to finish this time.
The manual does an okay job of explaining the rules for each of the
three development branches, but really doesn't give any intuition as
to why there are three (why not four? or two?) or how we got where
we are today.
This commit attempts to fix that, by explaining that there is one
branch that allows mass-rebuild commits, and it has a fast-building
branch both upstream and downstream of it (from the perspective of
automated merges).
I have also removed the term "stabilization" from the arc labels.
This vague term is not defined anywhere, and does communicate any
useful information without a longer explanation. Therefore it is
not appropriate for use in a diagram.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
It may have to be fetchpatch, fetchpatch2, or fetchurl. We should link somewhere, but we don't have a link target yet, so until then, remove the inaccurate info.
Co-authored-by: Alyssa Ross <hi@alyssa.is>
without stable ids on headings we cannot generate stable links to these
headings. nrd complains about this, but the current docbook workflow
does not.
a few generated ids remain, mostly in examples and footnotes. most of
the examples are generated by nixdoc (which has since gained MD export
functions, and the MD export does generate IDs).
this converts meta.doc into an md pointer, not an xml pointer. since we
no longer need xml for manual chapters we can also remove support for
manual chapters from md-to-db.sh
since pandoc converts smart quotes to docbook quote elements and our
nixos-render-docs does not we lose this distinction in the rendered
output. that's probably not that bad, our stylesheet didn't make use of
this anyway (and pre-23.05 versions of the chapters didn't use quote
elements either).
also updates the nixpkgs manual to clarify that option docs support all
extensions (although it doesn't support headings at all, so heading
anchors don't work by extension).
The thunderbird derivation is using `buildMozillaMach` these days,
shared with Firefox and Librefox, so it is probably the correct
, although more complicated, successor.
Move the manpage-to-URL mapping to `doc/manpage-urls.json` so that we can
reuse that file elsewhere, and generate the `link-manpages.lua` filter from
that file.
Also modify the Pandoc filter so that it doesn't wrap manpages that are
already inside a link.
Keeping a Lua filter is essential for speed: a Python filter would
increase the runtime `md-to-db.sh` from ~20s to ~30s (but Python is not
to blame; marshalling Pandoc types to and from JSON is a costly operation).
Parsing in Lua seems tedious, so I went with the Nix way.
The nixpkgs manual contains references to both sri hash and explicit
sha256 attributes. This is at best confusing to new users. Since the
final destination is exclusive use of sri hashes, see nixos/rfcs#131,
might as well push new users in that direction gently.
Notable exceptions to sri hash support are builtins.fetchTarball,
cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and
fetchCrate. None, other than builtins.fetchTarball, are fundamentally
incompatible, but all currently accept explicit sha256 attributes as
input. Because adding backwards compatibility is out of scope for this
change, they have been left intact, but migration to sri format has been
made for any using old hash formats.
All hashes have been manually tested to be accurate, and updates were
only made for missing upstream artefacts or bugs.
https://github.com/NixOS/nixpkgs/pull/89885 ensures that fetches are
done securely (i.e. without `--insecure`) when the `hash` parameter is one of
the four special "fake" hashes. However the manual was not updated in that PR.
This commit updates the manual to account for the already-merged changes from
that PR.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
