Improve the project guide (#5626)

docs/guides/projects.md

@@ -33,14 +33,15 @@ This will create the following directory structure:
 
 ### Working on an existing project
 
-If your project already contains a standard `pyproject.toml`, you can start using uv without any
+If your project already contains a standard `pyproject.toml`, you can start using uv immediately.
-extra work. Commands like `uv add` and `uv run` will create a lockfile and virtual environment the
+Commands like `uv add` and `uv run` will create a [lockfile](#uvlock) and [environment](#venv) the
 first time they are used.
 
 If you are migrating from an alternative Python package manager, you may need to edit your
-`pyproject.toml` manually before using uv. uv uses a `[tool.uv]` section in the `pyproject.toml` to
+`pyproject.toml` manually before using uv. Most Python package managers extend the `pyproject.toml`
-support features that are not yet included in the `pyproject.toml` standard, such as development
+standard to support common features, such as development dependencies. These extensions are specific
-dependencies. Alternative Python package managers may use different sections or format.
+to each package manager and will need to be converted to uv's format. See the documentation on
+[project dependencies](../concepts/dependencies.md) for more details.
 
 ## Project structure
 
@@ -70,50 +71,33 @@ remove` to manage your project through the CLI.
 
 !!! tip
 
-    See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for more details on getting started with the `pyproject.toml` format.
+    See the official [`pyproject.toml` guide](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) 
+    for more details on getting started with the `pyproject.toml` format.
 
 ### `.venv`
 
 The `.venv` folder contains your project's virtual environment, a Python environment that is
 isolated from the rest of your system. This is where uv will install your project's dependencies.
 
+See the [project environment](../concepts/projects.md#project-environments) documentation for more
+details.
+
 ### `uv.lock`
 
 `uv.lock` is a cross-platform lockfile that contains exact information about your project's
 dependencies. Unlike the `pyproject.toml` which is used to specify the broad requirements of your
-project, the lockfile contains the exact resolved versions that are installed in the virtual
+project, the lockfile contains the exact resolved versions that are installed in the project
 environment. This file should be checked into version control, allowing for consistent and
 reproducible installations across machines.
 
 `uv.lock` is a human-readable TOML file but is managed by uv and should not be edited manually.
 
-## Running commands
+See the [lockfile](../concepts/projects.md#lock-file) documentation for more details.
-
-`uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures
-that the lockfile and virtual environment are up-to-date before executing a given command:
-
-```console
-$ uv run python my_script.py
-$ uv run flask run -p 3000
-```
-
-Alternatively, you can use `uv sync` to manually synchronize the lockfile and virtual environment
-before executing a command:
-
-```console
-$ uv sync
-$ source .venv/bin/activate
-$ python my_script.py
-```
-
-!!! note
-
-    The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform.
 
 ## Managing dependencies
 
 You can add dependencies to your `pyproject.toml` with the `uv add` command. This will also update
-the lockfile and virtual environment:
+the lockfile and project environment:
 
 ```console
 $ uv add requests
@@ -135,6 +119,53 @@ To remove a package, you can use `uv remove`:
 $ uv remove requests
 ```
 
+See the documentation on [managing dependencies](../concepts/projects.md#managing-dependencies) for
+more details.
+
+
+## Running commands
+
+`uv run` can be used to run arbitrary scripts or commands in your project environment. This ensures
+that the lockfile and project environment are up-to-date before executing a given command.
+
+For example, to use `flask`:
+
+```console
+$ uv add flask
+$ uv run -- flask run -p 3000
+```
+
+Or, to run a script:
+
+```python title="example.py"
+# Require a project dependency
+import flask
+
+print("hello world")
+```
+
+```console
+$ uv run example.py
+```
+
+Alternatively, you can use `uv sync` to manually update the environment then activate it before
+executing a command:
+
+```console
+$ uv sync
+$ source .venv/bin/activate
+$ flask run -p 3000
+$ python example.py
+```
+
+!!! note
+
+    The virtual environment must be active to run scripts and commands in the project without `uv run`. Virtual environment activation differs per shell and platform.
+
+See the documentation on [running commands](../concepts/projects.md#running-commands) and [running
+scripts](../concepts/projects.md#running-scripts) in projects for more details.
+
 ## Next steps
 
-See the [projects concept](../concepts/projects.md) documentation for more details about projects.
+See the [projects concept](../concepts/projects.md) documentation for more details about working
+with projects.