search

NixOS / nixpkgs

Nix Packages collection & NixOS
MIT License
18.23k stars 14.22k forks source link

Doc: building manual don't work as described #82783

Open davidak opened 4 years ago

davidak commented 4 years ago

Describe the bug I searched the manual how to build the manual. I found system.build.manual.manualHTML.

https://nixos.org/nixos/manual/index.html#sec-building-parts

The chapter is called "Building Specific Parts of NixOS" but it's first sentence says "build specific parts of your NixOS configuration". That is not necessarily the same thing. Please clearify.

The part of NixOS i want to build is the manual, but my config is irelevant for that.

So having this error is stupid and bad UX.

[davidak@ethmoid:~/code/nixpkgs/nixos]$ nix-build -A config.system.build.manual.manualHTML
error: getting status of '/root/nixos-config/machines/ethmoid/configuration.nix': Permission denied

Sure i then found the correct method:

https://nixos.org/nixos/manual/index.html#sec-writing-docs-building-the-manual

It says "You can quickly validate your edits with make:" but again i get an error. It don't work when i follow the commands in the manual!

[davidak@ethmoid:~/code/nixpkgs/nixos/doc/manual]$ make
The program ‘make’ is currently not installed. It is provided by
several packages. You can install it by typing one of the following:
  nix-env -iA nixos.gnumake
  nix-env -iA nixos.gnumake42

Unlike everyone else, we have nix-shell. Use it! Getting such an error following our manual is just stupid (or bad UX).

Then there is the command to actually build the manual!

[davidak@ethmoid:~/code/nixpkgs/nixos/doc/manual]$ nix-build nixos/release.nix -A manual.x86_64-linux
error: getting status of '/home/davidak/code/nixpkgs/nixos/doc/manual/nixos/release.nix': No such file or directory

Again, following the manual leads to an error! There are 3 commands in this section and 2 fail!!! (doctests would be cool)

This is one reason why people don't contribute to the manual. It just don't work (as documented).

To Reproduce Steps to reproduce the behavior:

  1. follow the manual

Expected behavior things work

Metadata Current manual version is 19.09.

stale[bot] commented 4 years ago

Hello, I'm a bot and I thank you in the name of the community for opening this issue.

To help our human contributors focus on the most-relevant reports, I check up on old issues to see if they're still relevant. This issue has had no activity for 180 days, and so I marked it as stale, but you can rest assured it will never be closed by a non-human.

The community would appreciate your effort in checking if the issue is still valid. If it isn't, please close it.

If the issue persists, and you'd like to remove the stale label, you simply need to leave a comment. Your comment can be as simple as "still important to me". If you'd like it to get more attention, you can ask for help by searching for maintainers and people that previously touched related code and @ mention them in a comment. You can use Git blame or GitHub's web interface on the relevant files to find them.

Lastly, you can always ask for help at our Discourse Forum or at #nixos' IRC channel.

nh2 commented 4 years ago

Still relevant, I'd like to have clear instructions on how to build the manual.

stale[bot] commented 3 years ago

I marked this as stale due to inactivity. → More info