Skip to content
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.

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

documentation.nixos.enable: Default to false #83871

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

edolstra
Copy link
Member

@edolstra edolstra commented Mar 31, 2020

Generation of the manual is hugely expensive. For example, evaluation of the configuration of my laptop takes 3.97s realtime with documentation.nixos.enable set to true, but 2.42s with it set to
false. In other words, documentation generation accounts for 39% of evaluation time.

Given that the docs are readily available online (and in a more convenient form than man configuration.nix), it seems better to disable them by default.

Motivation for this change
Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • Determined the impact on package closure size (by running nix path-info -S before and after)
  • Ensured that relevant documentation is up to date
  • Fits CONTRIBUTING.md.

Generation of configuration.nix is hugely expensive. For example,
evaluation of the configuration of my laptop takes 3.97s realtime with
documentation.nixos.enable set to 'true', but 2.42s with it set to
'false'. In other words, documentation generation accounts for 39% of
evaluation time.

Given that the docs are readily available online (and in a more
convenient form than 'man configuration.nix'), it seems better to
disable them by default.
@grahamc
Copy link
Member

grahamc commented Mar 31, 2020

I wonder what it'd take to optionally disable generating docs for configuration.nix, but leave docs enabled for the CLI tooling. Then the configuration.nix could have a stub man page saying "Not generated because it is slow, see "

@vcunat
Copy link
Member

vcunat commented Mar 31, 2020

I don't know... for interactively used systems, one or two seconds of evaluation sounds quite cheap to me. For other systems it sounds better disabled by default. I'm not sure how to well differentiate among these, but if you agreed, we could at least approximate (say, those with graphical display managers).

@Mic92
Copy link
Member

Mic92 commented Mar 31, 2020

It might be also interesting how much memory it saves. Especially for low-memory devices. We should enable it on our installation images though because people might need to lookup documentation though.

@vcunat
Copy link
Member

vcunat commented Mar 31, 2020

Yes, though in those cases you probably want to completely avoid evaluating (on that machine).

@Mic92
Copy link
Member

Mic92 commented Mar 31, 2020

On my laptop it saves 2.3s/+60% (with documentation 5.916s, without 3.650s) evaluation time.

@romildo
Copy link
Contributor

romildo commented Mar 31, 2020

I am always using man configuration.nix to look for configuration help. It is nice tho have it readily available, even when no network is available. It will be missed.

@vcunat
Copy link
Member

vcunat commented Mar 31, 2020

Not in my case, as I'll add this option to my personal defaults if this gets merged ;-)

For a quick search man is more practical than a web browser, for me at least. Another advantage is consistency with system version; AFAIK there's still no comfortable link to nixos-unstable manuals, for example, but it's not just that.

@Mic92
Copy link
Member

Mic92 commented Mar 31, 2020

An alternative solution is to have a the manual build from a pre-evaluated xml dump. This one could be periodically updated in nixpkgs. The only disadvantage is that you won't have options generated for your own modules.

@vcunat
Copy link
Member

vcunat commented Mar 31, 2020

Yes, that would a middle route. I expect the xml could easily live in a separate repo.

@Mic92
Copy link
Member

Mic92 commented Mar 31, 2020

The other disadvantage of that approach is that we would need to sync this up ideally with channel updates or we get out-of-date configuration...

@vcunat
Copy link
Member

vcunat commented Mar 31, 2020

It could be done by a bot regularly... the main question is whether it's all worth it :-) (i.e. perhaps most people are OK with the two ways we have already)

@edolstra
Copy link
Member Author

@grahamc Yes, it would be nice to keep the other manpages.

@matthewbauer
Copy link
Member

Could we enable it for the installer profiles?

@evils
Copy link
Member

evils commented Apr 11, 2020

documentation should not be an opt-in

if you want users to opt-out, make it more visible in documentation with a note about its time savings
maybe output a reminder when evaluating this option that it can be turned off

perhaps a better way of making this kind of stuff visible, but probably a lot of work, could be to
make a systemd-analyze like tool for Nix
so users can decide for themselves if a feature is worth the (time) cost

@stale
Copy link

stale bot commented Oct 8, 2020

Hello, I'm a bot and I thank you in the name of the community for your contributions.

Nixpkgs is a busy repository, and unfortunately sometimes PRs get left behind for too long. Nevertheless, we'd like to help committers reach the PRs that are still important. This PR 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.

If this is still important to you and you'd like to remove the stale label, we ask that you leave a comment. Your comment can be as simple as "still important to me". But there's a bit more you can do:

If you received an approval by an unprivileged maintainer and you are just waiting for a merge, you can @ mention someone with merge permissions and ask them to help. You might be able to find someone relevant by using Git blame on the relevant files, or via GitHub's web interface. You can see if someone's a member of the nixpkgs-committers team, by hovering with the mouse over their username on the web interface, or by searching them directly on the list.

If your PR wasn't reviewed at all, it might help to find someone who's perhaps a user of the package or module you are changing, or alternatively, ask once more for a review by the maintainer of the package/module this is about. If you don't know any, you can use Git blame on the relevant files, or GitHub's web interface to find someone who touched the relevant files in the past.

If your PR has had reviews and nevertheless got stale, make sure you've responded to all of the reviewer's requests / questions. Usually when PR authors show responsibility and dedication, reviewers (privileged or not) show dedication as well. If you've pushed a change, it's possible the reviewer wasn't notified about your push via email, so you can always officially request them for a review, or just @ mention them and say you've addressed their comments.

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

@stale stale bot added the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Oct 8, 2020
@sorki
Copy link
Member

sorki commented Dec 3, 2020

I have documentation disabled on all of my arm devices as single-threaded xsltproc can take couple of minutes to finish.

I wonder if this gets better with the new CommonMark tooling.

@SuperSandro2000
Copy link
Member

SuperSandro2000 commented Dec 3, 2020

This change fails ofborg and I tend to always run man when I need to know something instead of searching online to make sure I have the right manual version.

@stale stale bot removed 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md labels Dec 3, 2020
@thiagokokada
Copy link
Contributor

Not completely against it, but I think it should go to the Breaking changes from manual (since I for one would be one of the people enabling it, I found it very useful).

@stale
Copy link

stale bot commented Jun 30, 2021

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

@stale stale bot added the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Jun 30, 2021
@Mic92
Copy link
Member

Mic92 commented Jul 1, 2021

still relevant.

@stale stale bot removed the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Jul 1, 2021
@stale
Copy link

stale bot commented Jan 3, 2022

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

@stale stale bot added the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Jan 3, 2022
@pennae
Copy link
Contributor

pennae commented Feb 22, 2023

is this still relevant with lazy options collection (which has massively decreased eval time)?

@stale stale bot removed the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Feb 22, 2023
@SuperSandro2000
Copy link
Member

This also removed the help pages for nixos tools like nixos-rebuild --help so we can't merge this as is IMO.

@SuperSandro2000 SuperSandro2000 marked this pull request as draft February 23, 2023 14:12
@wegank wegank added 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md 2.status: merge conflict labels Mar 19, 2024
@stale stale bot removed the 2.status: stale https://github.com/NixOS/nixpkgs/blob/master/.github/STALE-BOT.md label Mar 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet