Improve content on project configuration (#9235)

docs/concepts/projects/config.md

@@ -1,8 +1,24 @@
 # Configuring projects
 
+## Python version requirement
+
+Projects may declare the Python versions supported by the project in the `project.requires-python`
+field of the `pyproject.toml`.
+
+It is recommended to set a `requires-python` value:
+
+```toml title="pyproject.toml"
+[project]
+requires-python = ">=3.12"
+```
+
+The Python version requirement determines the Python syntax that is allowed in the project and
+affects selection of dependency versions (they must support the same Python version range).
+
 ## Entry points
 
-uv uses the standard `[project.scripts]` table to define entry points for the project.
+Projects may define entry points for the project in the `[project.scripts]` table of the
+`pyproject.toml`.
 
 For example, to declare a command called `hello` that invokes the `hello` function in the
 `example_package_app` module:
@@ -18,15 +34,26 @@ hello = "example_package_app:hello"
 
 ## Build systems
 
-Projects _may_ define a `[build-system]` in the `pyproject.toml`. The build system defines how the
-project should be packaged and installed.
+A build system determines how the project should be packaged and installed. Projects may declare and
+configure a build system in the `[build-system]` table of the `pyproject.toml`.
 
 uv uses the presence of a build system to determine if a project contains a package that should be
 installed in the project virtual environment. If a build system is not defined, uv will not attempt
 to build or install the project itself, just its dependencies. If a build system is defined, uv will
-build and install the project into the project environment. By default, projects are installed in
-[editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html) so changes to
-the source code are reflected immediately, without re-installation.
+build and install the project into the project environment.
+
+The `--build-backend` option can be provided to `uv init` to create a packaged project with an
+appropriate layout. The `--package` option can be provided to `uv init` to create a packaged project
+with the default build system.
+
+!!! note
+
+    While uv will not build and install the current project without a build system definition,
+    the presence of a `[build-system]` table is not required in other packages. For legacy reasons,
+    if a build system is not defined, then `setuptools.build_meta:__legacy__` is used to build the
+    package. Packages you depend on may not explicitly declare their build system but are still
+    installable. Similarly, if you add a dependency on a local package, uv will always attempt to
+    build and install it.
 
 ## Project packaging
 

docs/concepts/projects/dependencies.md

@@ -1,6 +1,19 @@
 # Managing dependencies
 
-uv is capable of adding, updating, and removing dependencies using the CLI.
+Dependencies of the project are defined in several tables:
+
+- [`project.dependencies`](./dependencies.md#project-dependencies): Published dependencies.
+- [`project.optional-dependencies`](./dependencies.md#optional-dependencies): Published optional
+  dependencies, or "extras".
+- [`dependency-groups`](./dependencies.md#dependency-groups): Local dependencies for development.
+
+!!! note
+
+    The `project.dependencies` and `project.optional-dependencies` tables can be used even if
+    project isn't going to be published. `dependency-groups` are a recently standardized feature
+    and may not be supported by all tools yet.
+
+uv supports modifying the project's dependencies with `uv add` and `uv remove`.
 
 ## Adding dependencies
 

docs/concepts/projects/layout.md

@@ -2,41 +2,29 @@
 
 ## The `pyproject.toml`
 
-Python project metadata is defined in a `pyproject.toml` file. uv requires this file to identify the
-root directory of a project.
+Python project metadata is defined in a
+[`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) file. uv
+requires this file to identify the root directory of a project.
 
 !!! tip
 
     `uv init` can be used to create a new project. See [Creating projects](./init.md) for
     details.
 
-A minimal project definition includes a name, version, and description:
+A minimal project definition includes a name and version:
 
 ```toml title="pyproject.toml"
 [project]
 name = "example"
 version = "0.1.0"
-description = "Add your description here"
 ```
 
-It's recommended, but not required, to include a Python version requirement in the `[project]`
-section:
+Additional project metadata and configuration includes:
 
-```toml title="pyproject.toml"
-requires-python = ">=3.12"
-```
-
-Including a Python version requirement defines the Python syntax that is allowed in the project and
-affects selection of dependency versions (they must support the same Python version range).
-
-The `pyproject.toml` also lists dependencies of the project in the `project.dependencies` and
-`project.optional-dependencies` fields. uv supports modifying the project's dependencies from the
-command line with `uv add` and `uv remove`. uv also supports extending the standard dependency
-definitions with [package sources](./dependencies.md) in `tool.uv.sources`.
-
-!!! tip
-
-    See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with a `pyproject.toml`.
+- [Python version requirement](./config.md#python-version-requirement)
+- [Dependencies](./dependencies.md)
+- [Build system](./config.md#build-systems)
+- [Entry points (commands)](./config.md#entry-points)
 
 ## The project environment