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,61 @@ 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](#libaries).
+
+## Project types
+
+uv supports two major types of projects, **applications** and **libaries**.
+
+### Applications
+
+Application projects are suitable for for web servers, scripts, and command-line interfaces.
+
+Application projects have the following traits:
+
+- A build backend is not required
+- Source code is often at the top-level, e.g., `hello.py`
+- The project package is not installed in the project environment by default
+
+By default, an application is not intended to be built and distributed as a Python package. However,
+the `--package` flag can be passed to `uv init` to create an application that is distributable,
+e.g., if you want to distribute a command-line interface via PyPI. When requested, uv will define a
+build backend for the project and install it into the project environment
+
+Similarly, a build backend can be manually defined to create a distributable package for an
+application. This may require changes to the project directory stucture, depending on the build
+backend. Once a build backend is defined, uv will attempt to install the project package into the
+project environment.
+
+### Libaries
+
+A library is a project that is intended to be built and distributed as a Python package. 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 `src/{package}/...` directories
+- 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 backend is a library.
+
+### Packages
+
+By default, any project that defines a build backend will be built and installed into the project
+environment. To disable build and installation of the project package, mark the project as
+unpackaged with [`tool.uv.package = false`](../reference/settings.md#package). uv will still install
+all of the project's dependencies.
+
 ## 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,28 @@ 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
+
+By default, `uv init` creates an [application](../concepts/projects.md#applications).
+
+To create a new, distributable application, use the `--package` flag:
+
+```
+$ uv init --package
+```
+
+Applications can also be converted to distributable at any time by setting
+[`tool.uv.package = true`](../reference/settings.md#package).
+
+Alternatively, create a new [library](../concepts/projects.md#libaries) using the `--lib` flag:
+
+```
+$ uv init --lib
+```
+
+For more details on types of projects, see the
+[projects concept](../concepts/projects.md#project-types) documentation.
+
 ## Building your package
 
 Build your package with the official `build` frontend: