docs: separate project from configuration settings

[mkniewallner]

Summary

Part of #7007.

Settings documentation reference currently doesn't separate "project metadata" and "configuration" options, implying that it's possible to set things like dev-dependencies in uv.toml while it's not. This is an attempt at better separating those options, by having 2 different sections:

• Project metadata, that holds configuration that can only be set in pyproject.toml
• Configuration, that holds configuration that can be set both in pyproject.toml and uv.toml

Here are some screenshots to show what this looks like (note that I don't have code highlighting in the right navigation, which makes them clunky, as first item is always bigger because of the missing "span" -- I think that's because it's an mkdocs-material insider feature, since I have the same thing on main branch):

• Right side navigation:

• An option from "Project metadata" section that only applies to pyproject.toml:

• An option from "Configuration" section that applies both to pyproject.toml and uv.toml:

Test Plan

Local run of the documentation.

[mkniewallner]

Not sure about the naming btw, went with "Project metadata" and "Configuration" but this might not be ideal. We might also consider adding a small description at the top of "Project metadata" section, to make it even more explicit why it's only possible to set those specific options in pyproject.toml.

[charliermarsh]

One oddity here that I need to resolve is that in the pip interface (uv pip), we will respect those settings in uv.toml (at least, constraints-dependencies etc., but not dev-dependencies).

[mkniewallner]

One oddity here that I need to resolve is that in the pip interface (uv pip), we will respect those settings in uv.toml (at least, constraints-dependencies etc., but not dev-dependencies).

Until we find a way to properly reflect that in the documentation, wouldn't it still be preferable to move forward with the changes? I feel that this is less problematic to only show pyproject.toml for options where it's also possible to use uv.toml in pip interface than showing uv.toml where it doesn't work for either both resolvers, or the universal one.

Worst case, obviously far from great, but if too complex for now, maybe we can "hack" around the issue by adding specific note on options where uv.toml only works for pip interface, e.g. either:

• adding a note like "If using pip interface, it's also possible to set the option in uv.toml like so: "
• using uv.toml (pip interface only) in the file header
• in the example, adding a comment "# This will only work for pip interface"

[charliermarsh]

Until we find a way to properly reflect that in the documentation, wouldn't it still be preferable to move forward with the changes?

I agree, it doesn't need to be blocking.

[charliermarsh]

What's the motivation for increasing the header size for the options? Is it because there are now two levels of nesting ("Project" -> "Workspace" -> "Members")? I wonder if we should use workspace.members there (as an example).

[mkniewallner]

What's the motivation for increasing the header size for the options? Is it because there are now two levels of nesting ("Project" -> "Workspace" -> "Members")? I wonder if we should use workspace.members there (as an example).

That's mostly the reason yes. Basically today we hack a bit things to have pip and workspace at the same level as Global, but now that we have 2 main categories ("Project" and "Configuration"), we want to add one more header level.

This is not really easy to see without digging into the HTML, but this is what we currently have:

Now we'll have: