Add mkEnableTargetWith and use it for documenting dynamic autoEnable conditions

[MattSturgeon]

Note

This PR is comprised of intentionally separate commits, please don't squash 🙂

This is a solution to the issues uncovered by #1212. This should fix #98 (not tested).

• Avoid evaluating dynamic conditions while rendering the docs.
• Define literal expressions describing dynamic conditions.
• Tested: all workarounds can be removed in #1212, when merged with this PR.

Previously, the literal markdown same as `stylix.autoEnable` was used. When an additional conditionText is supplied, it will now use the literal expression stylix.autoEnable && ${expr}.

If the expr contains any nix operators with a lower priority than &&, it will be auto-wrapped in parentheses, unless autoWrapExpr = false is used.

We could stick with the previous markdown approach, but I'm unsure what the best way to approach merging it with a autoEnableExpr or autoEnableText or autoEnableMD style arg would be. Suggestions and/or followup PRs welcome.

Things done

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

Notify relevant people

• @Flameopathic : related to mkTarget

[trueNAHO]

The implementation looks very nice :)

Should we merge this patchset with the following merge commit message:

treewide: add and apply mkEnableIf and mkEnableTargetWith functions

Link: https://github.com/nix-community/stylix/pull/1244

Reviewed-by: awwpotato <awwpotato@voidq.com>
Reviewed-by: NAHO <90870942+trueNAHO@users.noreply.github.com>

[trueNAHO]

it's getting frustrating to keep rebasing this, would it be possible to get a final review?

Sorry for letting this PR pend so long.

Either way, unless this patchset depends on new commits or this patchset would substantially change with the new commits, continuously running git rebase master is technically not required while the patchset itself is being discussed. A simpler approach would be to resolve the current state and git rebase master once at the very end just before merging the patchset.

Continuously running git rebase master does have the benefit that the patchset can be directly merged without requesting another git rebase master. This is a trade-off between being merge-ready and going insane with git rebase master. Although successfully completing git rebase master is its own reward.

[trueNAHO]

Looks great, except for one small question.

I would adapt my previous merge commit message (not squash commit message) proposal to the following:

treewide: use mkEnableTargetWith for dynamic autoEnable conditions

Use the new mkEnableTargetWith function for dynamic autoEnable
conditions to prevent the evaluation of dynamic conditions during
documentation rendering.

The 'same as `stylix.autoEnable`' defaultText is replaced with
'stylix.autoEnable' or 'stylix.autoEnable && ${autoEnableExpr}'
depending on whether autoEnableExpr is provided. For readability,
autoEnable expressions containing Nix operators of lower precedence than
'&&' are automatically wrapped in parentheses, unless autoWrapExpr is
disabled.

Closes: https://github.com/nix-community/stylix/issues/98
Link: https://github.com/nix-community/stylix/pull/1244

Reviewed-by: awwpotato <awwpotato@voidq.com>
Reviewed-by: NAHO <90870942+trueNAHO@users.noreply.github.com>
Reviewed-by: Daniel Thwaites <danth@danth.me>

Let's optimistically close #98 with this patchset. If this issue is in fact not resolved, we can simply re-open it.

[MattSturgeon]

I would adapt my previous merge commit message (not squash commit message) proposal to the following:

SGTM

Let's optimistically close #98 with this patchset. If this issue is in fact not resolved, we can simply re-open it.

SGTM. There are likely other cases of unintentionally dynamic docs values this PR hasn't caught, since it doesn't introduce any enforcement. But let's be optimistic for now!

[danth]

Latest revision looks good to me. Thanks for working on this :))

[stylix-automation]

Successfully created backport PR for release-25.05:

• [release-25.05] Add mkEnableTargetWith and use it for documenting dynamic autoEnable conditions #1470