[dg] Update uv integration guide (BUILD-973) (#29181)

## Summary & Motivation

- Rename the "uv integration" guide to "Python environment management
and uv integration"
- Update the content for accuracy/new APIs

Note that this will go through another iteration, I'm working on a
longer guide that explains `dg`'s process/environment architecture in
detail. I think this guide will be folded into that when it's done.

## How I Tested These Changes

Existing test suite.

Author: smackesey

docs/docs/guides/labs/dg/python-environment-management-and-uv-integration.md

@@ -0,0 +1,36 @@
+---
+title: 'Python environment management and `uv` integration'
+sidebar_position: 500
+---
+
+import Preview from '@site/docs/partials/\_Preview.md';
+
+<Preview />
+
+:::note
+
+We are working on streamlining the configuration of the `uv` integration, and it
+is likely to change in the next few releases.
+
+:::
+
+Many `dg` commands need to spawn subprocesses. For example, when you run `dg list plugins` in a project directory, `dg` does not perform an in-process inspection of the environment in which `dg` itself is running. Instead, it resolves a Python environment for the in-scope project and spawns a subprocess using the `dagster-components` executable (an internal API) in that environment. The output you see on the command line represents the plugins available in the resolved environment, which is not necessarily the same as the environment in which `dg` itself is running.
+
+The Python environment used for a project is determined by the `tool.dg.project.python_environment` setting in the project `pyproject.toml` file. This setting is either:
+
+- `active` (the default), which means that `dg` will use the currently active Python environment.
+- `persistent_uv` (not default, but set in dg-scaffolded projects by default), which means that `dg` will use a dedicated Python environment found in `<project_root>/.venv` that is created and managed by `uv`.
+
+If the setting is `active`, then `dg` does nothing fancy. It is up to the user to manage their own Python environments. If individual project-scoped environments are desired, the user must create them, and ensure the appropriate one is activated when running `dg` commands against that project.
+
+If the setting is `persistent_uv`, then `dg` will ignore any activated virtual environments. Subprocesses will be launched using `uv run`, which handles resolution of the project-scoped `.venv` environment and ensures subprocesses are launched in that environment. It also ensures that the environment is up to date with the project's specified dependencies before launching a subprocess.
+
+The `persistent_uv` setting is intended to ease development friction by removing the burden of juggling virtual environments from the user. It is our recommended configuration. However, we are still developing its functionality, and some users may prefer to totally opt out of any environment management "magic". These users should make sure all their projects use `tool.dg.project.python_environment = "active"`.
+
+:::info
+
+Disabling `uv` integration by setting `tool.dg.project.python_environment
+= "active"` will currently disable the `dg cache`. This will make some
+operations noticeably slower.
+
+:::

docs/docs/guides/labs/dg/scaffolding-a-project.md

@@ -32,4 +32,4 @@ The `dg init` command creates a directory with a standard Python package structu
 - `pyproject.toml` is a standard Python package configuration file. In addition
   to the regular Python package metadata, it contains a `tool.dg` section
   for `dg`-specific settings.
-- `uv.lock` is the [lockfile](https://docs.astral.sh/uv/concepts/projects/layout/#the-lockfile) for the Python package manager [`uv`](https://docs.astral.sh/uv/). `dg` projects use `uv` by default. For more information, see [`uv` integration](/guides/labs/dg/uv-integration).
+- `uv.lock` is the [lockfile](https://docs.astral.sh/uv/concepts/projects/layout/#the-lockfile) for the Python package manager [`uv`](https://docs.astral.sh/uv/). `dg` projects use `uv` by default. For more information, see [`uv` integration](/guides/labs/dg/python-environment-management-and-uv-integration).