Skip to content

Provide a schema for the htmlDocs output #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Provide a schema for the htmlDocs output #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
668a214
Provide a schema for the htmlDocs output
lucperkins Oct 2, 2025
c5ab930
Make inline docs more explicit
lucperkins Oct 2, 2025
4607008
Inherit what attribute
lucperkins Oct 2, 2025
a4f8981
Set isFlakeCheck to false
lucperkins Oct 2, 2025
46ef59f
Make function inline
lucperkins Oct 2, 2025
ce8c9c0
Update Nixpkgs for CI shell tools
lucperkins Oct 3, 2025
cf36798
Set full Nixpkgs URL as environment variable
lucperkins Oct 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/check.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,19 @@ permissions:
jobs:
flake-check:
runs-on: ubuntu-latest
env:
nixpkgs: "https://flakehub.com/f/NixOS/nixpkgs/0.2505.810656"
steps:
- uses: actions/checkout@v4
- uses: DeterminateSystems/determinate-nix-action@main
- uses: DeterminateSystems/flakehub-cache-action@main

- name: Check Nix formatting
run: |
nix shell "https://flakehub.com/f/NixOS/nixpkgs/0.2411.715026#nixfmt-rfc-style" --command \
nix shell "${{ env.nixpkgs }}#nixfmt-rfc-style" --command \
sh -c "git ls-files '*.nix' | xargs nixfmt --check"

- name: Check links in README
run: |
nix shell "https://flakehub.com/f/NixOS/nixpkgs/0.2411.715026#lychee" --command \
nix shell "${{ env.nixpkgs }}#lychee" --command \
lychee README.md
28 changes: 26 additions & 2 deletions flake.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,6 +335,30 @@
}) output
);
};

htmlDocsSchema = {
version = 1;
doc = ''
The `htmlDocs` flake output defines packages providing static HTML output.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice if we had a convention/requirement about what the entry point to the docs should be (e.g. there should be an $out/index.html) that we could document here (and maybe even enforce in the schema, though I don't think the meta-schema currently supports that). That way, tools like FlakeHub could provide a link to the docs automatically.

Currently this doesn't seem to be the case for Nixpkgs (it has entry points like $out/share/doc/nixpkgs/index.html).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would indeed be a nice convention. If you think the Nixpkgs folks would be amenable I could propose that upstream, but I suspect that a lot of things probably depend on that directory structure at this point.

'';
inventory =
output:
self.lib.mkChildren (
# This requires a special function because this output is structured
# htmlDocs.${package}.${system} rather than the usual ${output}.${system}.${package}
builtins.mapAttrs (packageName: systemsForPackage: {
forSystems = builtins.attrNames systemsForPackage;

children = builtins.mapAttrs (systemType: drv: {
forSystems = [ systemType ];
derivation = drv;
evalChecks.isDerivation = checkDerivation drv;
isFlakeCheck = false;
what = "HTML documentation";
}) systemsForPackage;
}) output
);
};
in

{
Expand All @@ -359,8 +383,7 @@
shortDescription = package.meta.description or "";
derivation = package;
evalChecks.isDerivation = checkDerivation package;
inherit what;
isFlakeCheck = isFlakeCheck;
inherit isFlakeCheck what;
}) packagesForSystem;
}) output
);
Expand All @@ -381,6 +404,7 @@
schemas.nixosModules = nixosModulesSchema;
schemas.homeConfigurations = homeConfigurationsSchema;
schemas.homeModules = homeModulesSchema;
schemas.htmlDocs = htmlDocsSchema;
schemas.darwinConfigurations = darwinConfigurationsSchema;
schemas.darwinModules = darwinModulesSchema;
schemas.dockerImages = dockerImagesSchema;
Expand Down