Skip to content

nixos/documentation: add nixpkgs-help #400381

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

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

nixos/documentation: add nixpkgs-help #400381

wants to merge 1 commit into from

Conversation

nezia1
Copy link
Member

@nezia1 nezia1 commented Apr 20, 2025

Adds an option to enable a local version of the nixpkgs manual, akin to what's already done with the NixOS manual (nixpkgs-help with a desktop entry for easy access). Closes #400374.

Things done

  • Built on platform(s)
    • x86_64-linux
    • aarch64-linux
    • x86_64-darwin
    • aarch64-darwin
  • For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
    • sandbox = relaxed
    • sandbox = true
  • Tested, as applicable:
  • Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
  • Tested basic functionality of all binary files (usually in ./result/bin/)
  • 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
    • (Package updates) Added a release notes entry if the change is major or breaking
    • (Module updates) Added a release notes entry if the change is significant
    • (Module addition) Added a release notes entry if adding a new NixOS module
  • Fits CONTRIBUTING.md.

Add a 👍 reaction to pull requests you find important.

@github-actions github-actions bot added 6.topic: nixos Issues or PRs affecting NixOS modules, or package usability issues specific to NixOS 8.has: module (update) This PR changes an existing module in `nixos/` labels Apr 20, 2025
@nezia1
Copy link
Member Author

nezia1 commented Apr 20, 2025

Should I write NixOS tests for this, as this adds an option? Or will this not be necessary?

@nezia1 nezia1 force-pushed the add-local-nixpkgs-manual branch from a09c2fc to db52842 Compare April 20, 2025 21:01
@github-actions github-actions bot added 10.rebuild-darwin: 1-10 This PR causes between 1 and 10 packages to rebuild on Darwin. 10.rebuild-linux: 1-10 This PR causes between 1 and 10 packages to rebuild on Linux. labels Apr 20, 2025
@nezia1 nezia1 marked this pull request as ready for review April 21, 2025 08:37
@nezia1
Copy link
Member Author

nezia1 commented Apr 21, 2025

nixpkgs-review result

Generated using nixpkgs-review.

Command: nixpkgs-review pr 400381

x86_64-linux

⏩ 2 packages blacklisted:
  • nixos-install-tools
  • tests.nixos-functions.nixos-test
✅ 5 packages built:
  • tests.devShellTools.nixos
  • tests.testers.lycheeLinkCheck.network
  • tests.testers.nixosTest-example
  • tests.testers.runNixOSTest-example
  • tests.trivial-builders.references

SigmaSquadron
SigmaSquadron reviewed Apr 21, 2025
View reviewed changes
SigmaSquadron
SigmaSquadron reviewed Apr 21, 2025
View reviewed changes
@nezia1 nezia1 force-pushed the add-local-nixpkgs-manual branch 2 times, most recently from 0a06cb7 to f6904c0 Compare April 21, 2025 22:56
@github-actions github-actions bot added 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin. and removed 10.rebuild-darwin: 1-10 This PR causes between 1 and 10 packages to rebuild on Darwin. labels Apr 21, 2025
@nezia1
Copy link
Member Author

nezia1 commented Apr 21, 2025 •
edited
Loading

I think we should be almost done (adding the release note later). However, the anchor links dont seem to work. I just get:

LibreWolf can’t find the file at /nix/store/pxd1xag13i26xn1894vvyjsyccdwgn92-nixpkgs-manual/share/doc/nixpkgs/index.html#part-stdenv

When trying to click any anchor. There seems to be a mismatch in the name, as the anchors reference index.html, while the file is manual.html. Unsure if this is a mistake in the derivation, or if we should substituteInPlace somehow?

@5225225
Copy link

5225225 commented Apr 22, 2025

The nixpkgs-manual derivation seems to explicitly move from index.html to manual.html...

that seems wrong? (at least without patching references of index.html to manual.html). Not sure why it does that. Is it only really meant to be served with the name index.html, remapped in a webserver or something?

nixpkgs/doc/doc-support/package.nix

Line 100 in 2966238

mv "$dest/index.html" "$dest/manual.html"

@nezia1
Copy link
Member Author

nezia1 commented Apr 22, 2025 •
edited
Loading

The nixpkgs-manual derivation seems to explicitly move from index.html to manual.html...

that seems wrong? (at least without patching references of index.html to manual.html). Not sure why it does that.

nixpkgs/doc/doc-support/package.nix

Line 100 in 2966238

mv "$dest/index.html" "$dest/manual.html"

This indeed looks very wrong. I fixed it in the linked sub-issue's PR (#400816), because the derivation just does not work for the time being. I don't understand what was the thought process behind it, as you cannot even parametrize it / there is no postInstall available in the derivation..

Is it only really meant to be served with the name index.html, remapped in a webserver or something?

You can generate it with nixos-render-doc to output the html to manual.html, but that does not build because it breaks references.json. I think this is the reason why the previous contributor moved it after generating it, but this just makes it not work since the anchors aren't updated accordingly. I couldn't find a place where nixpkgs-manual is used even within nixpkgs, which is why I'm suggesting just updating the path to index.html instead.

@nezia1 nezia1 requested a review from SigmaSquadron April 22, 2025 18:20
@wegank wegank added the 2.status: merge conflict This PR has merge conflicts with the target branch label Jun 9, 2025
acid-bong
acid-bong reviewed Jun 29, 2025
View reviewed changes
@nezia1 nezia1 force-pushed the add-local-nixpkgs-manual branch from f6904c0 to baeecfa Compare June 29, 2025 19:54
@nezia1
nixos/documentation: add nixpkgs-help
5116dff 
Adds an option to enable a local version of the nixpkgs manual, akin to
what's already done with the NixOS manual (`nixpkgs-help` with a desktop
entry for easy access).
@nezia1 nezia1 force-pushed the add-local-nixpkgs-manual branch from baeecfa to 5116dff Compare June 29, 2025 19:56
@ofborg ofborg bot removed the 2.status: merge conflict This PR has merge conflicts with the target branch label Jun 29, 2025
@nezia1 nezia1 requested a review from acid-bong June 30, 2025 14:21
SigmaSquadron
SigmaSquadron approved these changes Aug 15, 2025
View reviewed changes
Copy link
Contributor

@SigmaSquadron SigmaSquadron left a comment

Choose a reason for hiding this comment

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

This generally looks fine to me, but I would like to ask the @NixOS/documentation-team for their thoughts.

@nixpkgs-ci nixpkgs-ci bot added the 12.approvals: 1 This PR was reviewed and approved by one person. label Aug 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@SigmaSquadron SigmaSquadron SigmaSquadron approved these changes

@acid-bong acid-bong Awaiting requested review from acid-bong

Assignees
No one assigned
Labels
6.topic: nixos Issues or PRs affecting NixOS modules, or package usability issues specific to NixOS 8.has: module (update) This PR changes an existing module in `nixos/` 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin. 10.rebuild-linux: 1-10 This PR causes between 1 and 10 packages to rebuild on Linux. 12.approvals: 1 This PR was reviewed and approved by one person.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

nixos/documentation: add an option to enable the nixpkgs manual locally
5 participants
@nezia1 @5225225 @acid-bong @SigmaSquadron @wegank