In reply to @dimitarnestorov:matrix.org
Hey, could I get some guidance on this PR? What should I do next? Can I help somehow or maybe wait for something? https://github.com/NixOS/nixpkgs/pull/363755

Hello,

I'm trying to build the Nix manual following the instructions here:
https://nix.dev/manual/nix/2.25/development/documentation.

I have a few questions about the process:

1. Where should I run the build command?
   For example, do I need to be in a specific directory for the commands to work correctly?

2. Issues with nix-build output:
   When I run the following command in the src/nix directory:

   nix-build -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'
   

   It generates a result directory, but it does not contain the expected index.html
   in a path like ./result-doc/share/doc/nix/manual/index.html. Instead, I see several
   subdirectories with their own index.html files. Additionally, there is no
   result-doc directory, only result. Is this the intended behavior?

3. Error with nix build:
   When I try to use the newer command:

   nix build .#nix^doc
   

   I get the following error:

   error: derivation '/nix/store/91q76nmlb2aharvh227hlgv6xq78610m-nix-2.26.0pre20250102_442a262.drv' 
   does not have wanted outputs 'doc'
   

Could you clarify what might be going wrong or what adjustments I need to make? Thank you for your help!

Also when I try the third option, enter the development shell, and run:

[nix-shell:~/src/nix]$ make manual-html-open -j $NIX_BUILD_CORES
make: *** No rule to make target 'manual-html-open'.  Stop.

1. The Nix expression for nix-build is meant relative to the repo root, so you have to run it from there.

How all this works is not optimal, and that’s one reason I have rather strong opinions about the flakes complex…

1. This is probably an artefact in the documentation prose. The command is expected to produce result. I‘m confused why there’s no obvious entry point and will check when I‘m back at the keyboard

1. The instructions are outdated, flake.nix has been refactored apparently.

I‘m not even sure there’s a meaningful new-CLI way to do the same thing as with nix-build, but probably I’m wrong and not well-educated on the recently updated build setup and there’s a quick fix to make it nice.

In reply to @allrealmsoflife:matrix.org

Also when I try the third option, enter the development shell, and run:

[nix-shell:~/src/nix]$ make manual-html-open -j $NIX_BUILD_CORES
make: *** No rule to make target 'manual-html-open'.  Stop.

Okay, I built it. I do nix --version to get the version number and add that to the flake command: nix build nix/2.24.11\#nix^doc. Otherwise just the #nix^doc it won't work. One way to grab the version inside the command: nix build nix/$(nix --version | awk '{print $3}')#nix^doc

Now the flake command builds the result-doc while the nix-build command builds the result directories. Both results do have the index.html within the ./result-doc/share/doc/nix/manual/index.html or ./result/share/doc/nix/manual/index.html.

Okay, I built it. I do nix --version to get the version number and add that to the flake command: nix build nix/2.24.11#nix^doc. Otherwise just the #nix^docit won't work. One way to grab the version inside the command:nix build nix/$(nix --version | awk '{print $3}')#nix^doc`

Now the flake command builds the result-doc while the nix-build command builds the result directories. Both results do have the index.html within the ./result-doc/share/doc/nix/manual/index.html or ./result/share/doc/nix/manual/index.html.

Okay, I built it. I do nix --version to get the version number and add that to the flake command:

nix build nix/2.24.11#nix^doc

Otherwise just the #nix^docit won't work. One way to grab the version inside the command:

nix build nix/$(nix --version | awk '{print $3}')#nix^doc\

Now the flake command builds the result-doc while the nix-build command builds the result directories. Both results do have the index.html within the ./result-doc/share/doc/nix/manual/index.html or ./result/share/doc/nix/manual/index.html.

Okay, I built it. I do nix --version to get the version number and add that to the flake command:

nix build nix/2.24.11#nix^doc

Otherwise just the #nix^docit won't work. One way to grab the version inside the command:

nix build nix/$(nix --version | awk '{print $3}')#nix^doc\

Now the flake command builds the result-doc while the nix-build command builds the result directories. Both results do have the index.html within the ./result-doc/share/doc/nix/manual/index.html or ./result/share/doc/nix/manual/index.html.

Okay, I built it. I do nix --version to get the version number and add that to the flake command:

nix build nix/2.24.11#nix^doc

Otherwise just the #nix^docit won't work. One way to grab the version inside the command:

nix build nix/$(nix --version | awk '{print $3}')#nix^doc

Now the flake command builds the result-doc while the nix-build command builds the result directories. Both results do have the index.html within the ./result-doc/share/doc/nix/manual/index.html or ./result/share/doc/nix/manual/index.html.