stylix: honour recent docs to doc renames

[panchoh]

Starting with #1272, and followed by #1407, we are standardizing on doc (as in documentation), rather than docs (as in documents), following the current style of nixpkgs.

I’ve updated most remaining references to docs to reflect that, with the notable exclusion of serve-docs, which I’d like to rename to serve-doc in a follow-up PR.

Also note that I’ve extended the rename to nix build .#palette-generator.passthru.docs → nix build .#palette-generator.passthru.doc, without adding a deprecated alias, as was so diligently done by @MattSturgeon with the global .#docs → .#doc rename. If this is not acceptable, I’ll drop this change from this PR and add it to a subsequent, more proper one.

Things done

• Tested locally
• Tested in testbed
• Commit message follows commit convention
• (N/A) Fits style guide
• (N/A) Respects license of any existing code used

Notify maintainers

@awwpotato @danth @MattSturgeon @mightyiam @trueNAHO

[MattSturgeon]

Starting with #1272, and followed by #1407, we are standardizing on doc (as in documentation), rather than docs (as in documents), following the current style of nixpkgs.

Note that docs and doc are both short for documentation; neither is short for documents in this context.

"Documentation" is itself both a singular and plural noun. For whatever reason, "documentation" can be plural but "doc" cannot, so when shortened it gets an "s" to indicate it being a plural. 😁

We have standardised on doc for the directory and package name, largely because that matches nixpkgs, however this doesn't change the linguistics.

I’ve updated most remaining references to docs to reflect that, with the notable exclusion of serve-docs, which I’d like to rename to serve-doc in a follow-up PR.

Note that serve-docs is one case where I feel it is better to keep the plural form. You aren't serving a single piece of documentation, you are serving an entire website full of many pieces of documentation.

I can see a counter-argument, that you are in-fact serving the package (named "doc") as a website. But this feels off to me, which is why I didn't change it in #1407.

---

Also note that I’ve extended the rename to nix build .#palette-generator.passthru.docs -> nix build .#palette-generator.passthru.doc, without adding a deprecated alias. If this is not acceptable, I’ll drop this change from this PR and add it to a subsequent, more proper one.

IMO this is fine, assuming palette-generator.docs is a niche and rarely used passthru. If it is expected to be used by end-users or third-party contributors, then it should have a deprecation warning.

Note that even without any manual deprecation, the error produced by nix when an attr is missing is fairly helpful, it usually even suggests fixes for potential typos:

nix-repl> { doc = null; }.docs
error: attribute 'docs' missing
       at «string»:1:1:
            1| { doc = null; }.docs
             | ^
       Did you mean doc?

[panchoh]

Starting with #1272, and followed by #1407, we are standardizing on doc (as in documentation), rather than docs (as in documents), following the current style of nixpkgs.

Note that docs and doc are both short for documentation; neither is short for documents in this context.

"Documentation" is itself both a singular and plural noun. For whatever reason, "documentation" can be plural but "doc" cannot, so when shortened it gets an "s" to indicate it being a plural. 😁

Thanks for the enlightenment, @MattSturgeon!

We have standardised on doc for the directory and package name, largely because that matches nixpkgs, however this doesn't change the linguistics.

I’ve updated most remaining references to docs to reflect that, with the notable exclusion of serve-docs, which I’d like to rename to serve-doc in a follow-up PR.

Note that serve-docs is one case where I feel it is better to keep the plural form. You aren't serving a single piece of documentation, you are serving an entire website full of many pieces of documentation.

I see your point. My way of thinking about it is more in the lines of “serve the documentation this project might have”; I’m not concerned with how many pieces the documentation might have. Be one or two hundred, it feels the same to me at this level of abstraction. But that’s just the way I think, I won’t pursue this any further. Thanks again for the detailed explanation.

I can see a counter-argument, that you are in-fact serving the package (named "doc") as a website. But this feels off to me, which is why I didn't change it in #1407.

Ah, I hadn’t thought of that. But interesting nonetheless.

---

Also note that I’ve extended the rename to nix build .#palette-generator.passthru.docs -> nix build .#palette-generator.passthru.doc, without adding a deprecated alias. If this is not acceptable, I’ll drop this change from this PR and add it to a subsequent, more proper one.

IMO this is fine, assuming palette-generator.docs is a niche and rarely used passthru. If it is expected to be used by end-users or third-party contributors, then it should have a deprecation warning.

Note that even without any manual deprecation, the error produced by nix when an attr is missing is fairly helpful, it usually even suggests fixes for potential typos:

nix-repl> { doc = null; }.docs
error: attribute 'docs' missing
       at «string»:1:1:
            1| { doc = null; }.docs
             | ^
       Did you mean doc?

Thanks for the thorough analysis, very much appreciated! Since @danth gave a thumbs-up to your comment, I went ahead and kept the change in.

BTW, I’m having so much fun being here. <3

[MattSturgeon]

Couple issues with the rebase, otherwise good

[panchoh]

Couple issues with the rebase, otherwise good

Ouch. Apologies! Fixing it now…

[panchoh]

And sorry, I should have inspected the commit after the first (failed) rebase, and I would have noticed the spurious changes.
Won’t happen again.

[MattSturgeon]

And sorry, I should have inspected the commit after the first (failed) rebase, and I would have noticed the spurious changes.
Won’t happen again.

Don't worry it's easily done 😁

[0xda157]

LGTM

[stylix-automation]

Successfully created backport PR for release-25.05:

• [release-25.05] stylix: honour recent docs to doc renames #1519