Provide a schema for the htmlDocs output #44
Conversation
WalkthroughAdds an htmlDocsSchema to flake.nix that defines a package-first inventory producing HTML documentation derivations, exposes it as Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer
participant Flake as flake.nix (outputs)
participant Schema as htmlDocsSchema
participant Inv as derivationsInventoryByPackage
participant Systems as Systems
participant Packages as Packages
participant Docs as HTML Doc Derivations
Dev->>Flake: Query outputs.schemas.htmlDocs
Flake->>Schema: Initialize htmlDocsSchema
Schema->>Inv: Request package-first inventory
Inv->>Systems: Iterate systems
Systems->>Packages: yield package sets
Packages->>Inv: packages per system
Inv->>Docs: Map package → HTML doc derivation
Docs-->>Schema: return HTML docs inventory
Schema-->>Flake: expose as schemas.htmlDocs
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
🔇 Additional comments (5)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
flake.nix (1)
349-354: Consider addingshortDescriptionfor consistency.Other derivation-based schemas (like
packagesSchemaanddevShellsSchema) extractshortDescriptionfrom package metadata. Adding this field would provide useful context when inventorying HTML documentation packages.Apply this diff to add
shortDescription:children = builtins.mapAttrs (systemType: drv: { forSystems = [ systemType ]; + shortDescription = drv.meta.description or ""; derivation = drv; evalChecks.isDerivation = checkDerivation drv; what = "HTML documentation"; }) systemsForPackage;
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
flake.nix(2 hunks)
🔇 Additional comments (1)
flake.nix (1)
411-411: LGTM!The schema export is correctly added to the top-level
schemasmapping.
|
It's worth noting that the order of the attributes in Since |
| htmlDocsSchema = { | ||
| version = 1; | ||
| doc = '' | ||
| The `htmlDocs` flake output defines packages providing static HTML output. |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
With this schema in place,
nix flake show nixpkgs --all-systemsdisplays this forhtmlDocs:I'm not sure this will be used outside of Nixpkgs but it would be nice to be able to support all Nixpkgs outputs.
Summary by CodeRabbit