This new mode is supposed to absorb content that is currently added via --infile and recursive {=include=}
As we restructure the nixpkgs manual we are going to add pages to this file
As a result we end up with a config file that describes the sidebar structure and what files map to which entry
This is needed for 'docs.nixos.org' navigation cutover; which will consume this file along with the .md files and render it into the portal
tables of contents disconnect headings from body text.
decouples heading levels from include type (part,chapter,part etc.)
structure of the sidebar is derived from the include type for now.
Can be changed to a meta file later.
sidebar now uses proper ol-, li-, span-, a-tags
definition tables are not ideal for navigation and accessibility
breaking change:
--toc-depth, --chunk-toc-depth, --section-toc-depth is
now collapsed into --sidebar-depth
This was run as a test in `doc/tests/check-nix-code-blocks.nix` before,
but its DX can be improved: By including it in `treefmt` we get better
error reporting and auto-fixing, as well as running it on *all* markdown
files (including READMEs etc.) for free.
Add a `treefmt.optionsDoc` passthru, which is included on the treefmt
section of the nixpkgs manual.
This generates reference docs for options declared in
`treefmt.evalConfig`.
Add a `treefmt.functionsDoc` passthru, which is included on the treefmt
section of the nixpkgs manual.
This generates reference docs for functions defined in
`pkgs/by-name/tr/treefmt/lib.nix`, using `nixdoc`.
Roboto was already set as the font for the manuals,
but without a way to get it, so people who didn't
happen to have it installed saw their default font
I don’t love this, and I’m not convinced it doesn’t have the
same pitfalls as filesets, but see the `flattenReferencesGraph`
commit for reasoning.
It may be better to ban the relevant builtins entirely and just move
things into subdirectories when needed, but I didn’t want to do
more surgery to this part of the tree than necessary to solve the
immediate problem.
the `devmode` helper made for the Nixpkgs/NixOS manual was exposed wrapped
in `mkShell`, which made it impossible to reuse.
this change strips that wrapper and reproduces it at the call site.
now one can use `devmode` from anywhere Nixpkgs is available:
devmode = pkgs.callPackage "${pkgs.path}/pkgs/tools/nix/web-devmode.nix" {
buildArgs = toString ./.;
open = "/index.html";
};
`lib.trivial.revisionWithDefault` will change with every Git commit, which causes the manual to be rebuilt on every since PR.
Using `nixpkgs.rev` (or the dummy value "master" if it's not present) means that the manual will contain the revision if built on Hydra, but will not otherwise.
Why?
1. https://hydra.nixos.org/jobset/nixos/trunk-combined#tabs-configuration shows that `pkgs/top-level/release.nix` is passed the `nixpkgs` attrset, which is a "Git checkout".
2. Git checkouts come from [`builtins.fetchGit`](https://nix.dev/manual/nix/2.18/language/builtins#builtins-fetchGit) and include the `rev` attribute.
3. The `rev` attribute is what `lib.trivial.revisionWithDefault` would have returned.
So, using `nixpkgs.rev or "master"` exclusively will cause the rebuilds on every commit to cease, but will allow "official" nixpkgs manual built on Hydra to continue to reference a specific commit.
