Update project documentation for the application / library concepts

docs/concepts/projects.md

@@ -10,7 +10,10 @@ Python projects help manage Python applications spanning multiple files.
 
 Python project metadata is defined in a `pyproject.toml` file.
 
-`uv init` can be used to create a new project, with a basic `pyproject.toml` and package definition.
+!!!
+
+    `uv init` can be used to create a new project. See [Creating projects](#creating-projects) for
+    details.
 
 A minimal project definition includes a name, version, and description:
 
@@ -21,7 +24,7 @@ version = "0.1.0"
 description = "Add your description here"
 ```
 
-Additionally, it's recommended to include a Python version requirement:
+It's recommended, but not required, to include a Python version requirement:
 
 ```toml title="pyproject.toml"
 [project]
@@ -39,6 +42,72 @@ dependency list from the command line with `uv add` and `uv remove`. uv also sup
 
     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`.
 
+## Creating projects
+
+uv supports initializing a project with `uv init`. By default, uv will create a project in the
+working directory. Projects can be created in a target directory by providing a name, e.g.,
+`uv init foo`. If there's already a project in the target directory, i.e., there's a
+`pyproject.toml`, uv will exit with an error.
+
+By default, uv will create a project for an [application](#applications). However, the `--lib` flag
+can be used to create a project for a [library](#libraries).
+
+## Project types
+
+uv groups projects into two types: **applications** and **libraries**.
+
+### Applications
+
+Application projects are suitable for web servers, scripts, and command-line interfaces.
+
+Application projects have the following traits:
+
+- A build backend is not defined.
+- Source code is often in the top-level directory, e.g., `hello.py`.
+- The project package is not installed in the project environment.
+
+!!! note
+
+    The `--package` flag can be passed to `uv init` to create a distributable application,
+    e.g., if you want to publish a command-line interface via PyPI. uv will define a build
+    backend for the project, include a `[project.scripts]` entrypoint, and install the project
+    package into the project environment.
+
+    Similarly, a build backend can be manually defined to treat any application as a distributable
+    package. This may require changes to the project directory structure, depending on the build
+    backend.
+
+### Libraries
+
+A library is a project that is intended to be built and distributed as a Python package, for
+example, by uploading it to PyPI. A library provides functions and objects for other projects to
+consume.
+
+Library projects have the following traits:
+
+- A build backend is required.
+- Source code is typically in a `src/{package}` directory.
+- The project package is installed in the project environment.
+
+Libraries can be created with `uv init` by providing the `--lib` flag. uv will assume that any
+project that defines a `[build-system]` is a library.
+
+### Other types
+
+By default, uv uses the presence of a `[build-system]` in the `pyproject.toml` to determine if a
+project is an application or a library. However, uv also allows manually declaring if a project
+should be treated as a package.
+
+To enable or disable build and installation of the project package regardless of the presence of a
+`[build-system]` definition, use the [`tool.uv.package`](../reference/settings.md#package) setting.
+
+Setting `tool.uv.package = true` will force a project package to be built and installed into the
+project environment. If no build system is defined, uv will use the setuptools legacy backend.
+
+Setting `tool.uv.package = false` will force a project package _not_ to be built and installed into
+the project environment. uv will ignore the declared build system, if any, when interacting with the
+project.
+
 ## Project environments
 
 uv creates a virtual environment in a `.venv` directory next to the `pyproject.toml`. This virtual

docs/guides/projects.md

@@ -1,7 +1,6 @@
 # Working on projects
 
-uv is capable of managing Python projects using a `pyproject.toml` with a `[project]` metadata
-table.
+uv supports managing Python projects, which define their dependencies in a `pyproject.toml` file.
 
 ## Creating a new project
 
@@ -20,34 +19,42 @@ $ cd hello-world
 $ uv init
 ```
 
-This will create the following directory structure:
+uv will create the following files:
 
 ```text
 .
-├── pyproject.toml
 ├── README.md
-└── src
-    └── hello_world
-        └── __init__.py
+├── hello.py
+└── pyproject.toml
 ```
 
-### Working on an existing project
-
-If your project already contains a standard `pyproject.toml`, you can start using uv immediately.
-Commands like `uv add` and `uv run` will create a [lockfile](#uvlock) and [environment](#venv) the
-first time they are used.
+The `hello.py` file contains a simple "Hello world" program. Try it out with `uv run`:
 
-If you are migrating from an alternative Python package manager, you may need to edit your
-`pyproject.toml` manually before using uv. Most Python package managers extend the `pyproject.toml`
-standard to support common features, such as development dependencies. These extensions are specific
-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.
+```console
+$ uv run hello.py
+Hello from hello-world!
+```
 
 ## Project structure
 
 A project consists of a few important parts that work together and allow uv to manage your project.
-Along with the files created by `uv init`, uv will create a virtual environment and `uv.lock` file
-in the root of your project the first time you run a project command.
+In addition to the files created by `uv init`, uv will create a virtual environment and `uv.lock`
+file in the root of your project the first time you run a project command, i.e., `uv run`,
+`uv sync`, or `uv lock`.
+
+A complete listing would look like:
+
+```text
+.
+├── .venv
+│   ├── bin
+│   ├── lib
+│   └── pyvenv.cfg
+├── README.md
+├── hello.py
+├── pyproject.toml
+└── uv.lock
+```
 
 ### `pyproject.toml`
 
@@ -60,20 +67,20 @@ version = "0.1.0"
 description = "Add your description here"
 readme = "README.md"
 dependencies = []
-
-[tool.uv]
-dev-dependencies = []
 ```
 
-This is where you specify dependencies, as well as details about the project such as its description
-or license. You can edit this file manually, or use commands like `uv add` and `uv remove` to manage
-your project through the CLI.
+You'll use this file to specify dependencies, as well as details about the project such as its
+description or license. You can edit this file manually, or use commands like `uv add` and
+`uv remove` to manage your project from the terminal.
 
 !!! 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.
 
+You'll also use this file to specify uv [configuration options](../configuration/files.md) in a
+[`[tool.uv]`](../reference/settings.md) section.
+
 ### `.venv`
 
 The `.venv` folder contains your project's virtual environment, a Python environment that is

docs/guides/publish.md

@@ -4,6 +4,16 @@ uv does not yet have dedicated commands for building and publishing a package. I
 the PyPA tools [`build`](https://github.com/pypa/build) and
 [`twine`](https://github.com/pypa/twine), both of which can be invoked via `uvx`.
 
+## Preparing your project for packaging
+
+Before attempting to publish your project, you'll want to make sure it's ready to be packaged for
+distribution.
+
+If your project does not include a `[build-system]` definition in the `pyproject.toml`, uv will not
+build it by default. This means that your project may not be ready for distribution. Read more about
+the effect of declaring a build system in the
+[project concept](../concepts/projects.md#project-types) documentation.
+
 ## Building your package
 
 Build your package with the official `build` frontend: