- Use separate JSON files to track sources for Nixpkgs and Nix releases
This greatly simplifies the code, because we can directly encode
versions as keys without ambiguity
- Avoid an instance of IFD for the redirect generation
- Use pkgs.substitute instead of builtins.replaceStrings
- Turn off the single-page feature for now. It was added by Valentin in
a previous commit, but I think we should discuss this a bit more
- Simplify a lot of the code and add comments
- Fix the mutable redirects, they were broken by a parent commit
- Remove pieces of Nix code that weren't used, like the import of the
Nixpkgs manual. This can be added in the future when necessary
- Make sure that Nix versions are cached by building from the store path
this will accumulate releases over time. it's not great, but this is the
price of persistent URLs. otherwise, when people link to supposedly stable
URLs, and we garbage-collect old manuals, those links will rot away.
it's also slightly simpler algorithmically, and therefore easier to
reason about.
this can be incrementally improved in the future, by automatically
adding redirects to e.g. the closest following release for which the
manual is still served. for example, if we currently serve
23.11
23.05
22.11
22.05
but in the future decide to cut that list to the first two, the script
would drop the excess pins and add redirects like these:
/manual/nixpkgs/22.05/* /manual/nixpkgs/23.05/:splat 301
/manual/nixpkgs/22.11/* /manual/nixpkgs/23.05/:splat 301
the condition for that would be that we are reasonably sure that the
manuals will manage their own internal redirects as pages and anchors
move around between releases.
previously, stderr was garbled, which made it really annoying to deal
with build errors.
it turns out that the library wrapper around calling a process is not
just counterproductive, but also completely unnecessary.
the build now takes longer because it's not incremental any more.
but the problem with `sphinx-build` in a shell environment is that it
doesn't keep track of an entire class of files, that would have to be
considered manually. this is too much manual overhead that doesn't scale
at all. with the new setup the live preview will do exactly what the
final deployment does.
[1]: https://github.com/executablebooks/sphinx-autobuild#relevant-sphinx-bugs
Co-authored-by: Alex Groleau source@proof.construction
this is the most cursed setup you will see any time soon.
we're dumping the Nix manual unchanged into the build tree *after*
building. the reason is that we'd want to link to it from our table of
contents, but because Sphinx does not allow adding arbitrary files to
the build output in arbitrary locations (only `_static` works). but we
want to place the manual behind a particular URL, and the alternative of
maintaining URL rewrites (e.g. in nginx) is not accessible here because the
infrastructure is managed somewhere else.
now that the files won't appear in their desired locations at Sphinx
build time, we can't use relative links to reference them, therefore we
have to resort to pointing to the web URL the manual will appear at.
this is terrible and I'm sorry. please fix this if you have a better
idea. once we use URLs though, we have to avoid linkchecking, since
those files may not be there before deploying them.
figuring all of this out took way longer than anyone would wish.
Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
use niv for dependency management.
this follows our own tutorials on writing packages and development
shells, and we generally find it is easier to read and work with.
Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>
