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.
After final improvements to the official formatter implementation,
this commit now performs the first treewide reformat of Nix files using it.
This is part of the implementation of RFC 166.
Only "inactive" files are reformatted, meaning only files that
aren't being touched by any PR with activity in the past 2 months.
This is to avoid conflicts for PRs that might soon be merged.
Later we can do a full treewide reformat to get the rest,
which should not cause as many conflicts.
A CI check has already been running for some time to ensure that new and
already-formatted files are formatted, so the files being reformatted here
should also stay formatted.
This commit was automatically created and can be verified using
nix-build https://github.com/infinisil/treewide-nixpkgs-reformat-script/archive/a08b3a4d199c6124ac5b36a889d9099b4383463f.tar.gz \
--argstr baseRev b32a094368
result/bin/apply-formatting $NIXPKGS_PATH
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";
};
The darwin sandbox prevents this nix call from accessing `/nix/
store/.links` resulting in a build failure:
```
> error: getting status of '/nix/store/.links': Operation not permitted
```
Thanks to @emilazy for the workaround!
Fixes https://github.com/NixOS/nixpkgs/issues/339808
`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.
Problem: `nix-build doc` gives a bunch of warnings because it inspects
`lib` to figure out where all the symbols are.
Solution: Move the step of figuring out where the symbols are to
a Nix evaluation inside a derivation instead.
* doc: autogenerate python interpreter table
This serves as a practical example on generating documentation by
inspection of the evaluated Nixpkgs tree.
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
separating function docs out like this makes it less clear how library
documentation is generated and integrated into the build. if in the
future more parts of nixpkgs use nixdoc it will make sense to have all
information about library doc generation in the same place.
Johannes Kirschbauer