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>
* Draft module system introduction tutorial
* add intro/conclusion, rework prose, follow styleguide, clean diffs
* Review pass
* Apply suggestions from code review
* fix whitespace
* add some more motivation the each section
* make scripts downloadable
* address review comments
* make script actually work
...hopefully. can't test it without Google API key
* add file watching
yes, this looks scary, and yes, it works.
* update diff and wording
* more notes on potential pitfalls
* be explicit which `map` we mean
* split nullable from default values
* also wrap the geocode script
* work through the tutorial to the end
* add tutorial overview
* `lib` is always passed
* add separate section for `evalModules` and fix link
* make option strucutre more self-explanatory
* explain command line invocations
* add note on incomplete reference documentation
* add more highlight to the `config` distinction
* fix parameter passing to the `./map` script
* fix typo
* fix wording
* link to summer of nix
* add missing word
* link to Google Maps API docs
* more explicit requirement
* use correct module system terminology
* Update source/tutorials/module-system/module-system.md
* Apply suggestions from code review
* whitespace
* module-system.md: replace comments with captions
* add missing lang for code-block
* Update module system title
* change most headers to be about module features (#797)
* change most headers to be about module features
Some headers could not be made about module features, and that's a
strong signal that those sections should be removed.
* Apply suggestions from code review
* module-system.md: Fix header casing
Co-authored-by: Alexander Groleau <source@proof.construction>
Co-authored-by: asymmetric <lorenzo@mailbox.org>
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
recent additions to the Nix manual clarify the distinction between
search path and lookup path, and also document the resolution algorithm.
lookup paths are now a distinct Nix language construct with its own
reference documentation.
* Remove specific software name from header
There's enough detail about it below, and the specific tech isn't the point of this section anyway.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
* rewrite guide to pinning dependencies with niv
* use the specific branch directly
Co-authored-by: Silvan Mosberger <github@infinisil.com>
* use the shell's niv explicitly
* Apply suggestions from code review
---------
Co-authored-by: Silvan Mosberger <github@infinisil.com>
This does not yet follow #701, because the change to get there would be
too big. The goal is to keep the table of contents meaningful at all
times and the diff of each pull request manageable.
The packaging tutorial is quite important, so it's not wrong to have it
visible on the front page until we have enough material for a packaging
section.
The sharing dependencies article should really be a very brief guide, but
because that would be quite a big change, it's only moved to the Guides
section for now.
* add Recipes section under Guides category
This also removes the templates section, as we're not maintaining it and it likely won't be necessary anyway once the curriculum is roughly finished.
the instructions say that the command will open a window, which
naturally requires a graphical environment. but this is very late in the
process, and will likely not be obvious in the middle of a a self-directed learning situation.
* move 'are there...impurities in builds?' -f recipes -t concepts
* reword some items and add links/more info
* fix random bullet point
* rm nix hour ref
* rm home directory bullet point
* reword question to make it more specific
* add back filesystem item
* replace passive to keep list's theme
* fix typo
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
* add nix version item to the list
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
* add binfmt to linux kernel items
---------
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
rephrase slightly for brevity and clarity.
re-use the examples from the ad-hoc environment tutorial both for
simplicity as well as to give it some continuity.
Co-authored-by: Alexander Groleau <alex@proof.construction>
remove references to "towards reproducibility" as that's not very
focused, and at that point readers will likely be familiar with the
concept such that they only need the reference, if anything
this fits the global outline we developed, and also makes the tutorial
more immediately visible - working with the Nix language is a core skill
we want to teach after all
readers don't even need to think about it, as it's encoded in the pinned
source. at best this would be a note to maintainers, but we should know
that as well.
- use the same Nixpkgs release to avoid massive downloads
- continue using `pkgs.nixosTest`; the new thing is completely undocumented
- use a shorthand module; `lib` is not used
- use an empty nginx config; commented-out code is confusing
- move explanation of the test script to the end; use imperative
- add instructions to run it
while section headings are good for linking, this is not very important
here. the heading distract from the sequential structure, which the list
exposes more clearly.
change "build task" to "derivation" in tutorial
"build task" invokes associations with pre-existing knowledge. As long as they are clearly explained, it is easier for beginners to pick up a new word than it is to add a new definition to an existing word that subtly differs from the other definitions it has. To that extent, "derivation" is probably a great word for Nix as, at least in this domain, it is very Nix specific and so, with clear definition, it should be easy to convey the idea to other folks that we are talking about something Nix specific.
The cross compilation documentation is showing, at some point, two
variations on how to get a cross-compiled package out of Nixpkgs. Those
two versions are strictly equivalent (the only difference is what part
of the full attribute set paths is put in the variable named `pkgs`) and
don't really improve understanding - arguably, rather hurts it.
