From 86c8906d103b62a9687fefd24a431e84da9d3dd2 Mon Sep 17 00:00:00 2001
From: my1e5 <10064103+my1e5@users.noreply.github.com>
Date: Thu, 5 Sep 2024 00:22:34 +0100
Subject: [PATCH] Update docs on `.python-version` file (#7051)

## Summary

Closes https://github.com/astral-sh/uv/issues/7027

* When displaying the file structure of a uv-managed project show the
`.python-version` file which is now created by default.
* Mention the purpose of the `.python-version` file in `Guides/Working
on projects/Project structure`
* In `Concepts/Python versions/Project python versions`, changed
sentence about `.python-version` file to reflect the fact it is included
by default so is likely to be present.
---
 docs/concepts/projects.md        | 3 +++
 docs/concepts/python-versions.md | 4 ++--
 docs/guides/projects.md          | 7 +++++++
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md
index 863dd6c23873..263f9438266c 100644
--- a/docs/concepts/projects.md
+++ b/docs/concepts/projects.md
@@ -106,6 +106,7 @@ Applications are the default target for `uv init`, but can also be specified wit
 $ uv init --app example-app
 $ tree example-app
 example-app
+├── .python-version
 ├── README.md
 ├── hello.py
 └── pyproject.toml
@@ -155,6 +156,7 @@ Libraries can be created by using the `--lib` flag:
 $ uv init --lib example-lib
 $ tree example-lib
 example-lib
+├── .python-version
 ├── README.md
 ├── pyproject.toml
 └── src
@@ -217,6 +219,7 @@ The project structure looks the same as a library:
 $ uv init --app --package example-packaged-app
 $ tree example-packaged-app
 example-packaged-app
+├── .python-version
 ├── README.md
 ├── pyproject.toml
 └── src
diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md
index 8553795ba6d8..3b1bcc058791 100644
--- a/docs/concepts/python-versions.md
+++ b/docs/concepts/python-versions.md
@@ -96,8 +96,8 @@ are used for requesting local interpreters such as a file path.
 By default `uv python install` will verify that a managed Python version is installed or install the
 latest version.
 
-However, a project may define a `.python-version` file specifying the default Python version to be
-used. If present, uv will install the Python version listed in the file.
+However, a project may include a `.python-version` file specifying a default Python version. If
+present, uv will install the Python version listed in the file.
 
 Alternatively, a project that requires multiple Python versions may also define a `.python-versions`
 file. If present, uv will install all of the Python versions listed in the file. This file takes
diff --git a/docs/guides/projects.md b/docs/guides/projects.md
index c5a477ffed1b..e34806938a91 100644
--- a/docs/guides/projects.md
+++ b/docs/guides/projects.md
@@ -23,6 +23,7 @@ uv will create the following files:
 
 ```text
 .
+├── .python-version
 ├── README.md
 ├── hello.py
 └── pyproject.toml
@@ -50,6 +51,7 @@ A complete listing would look like:
 │   ├── bin
 │   ├── lib
 │   └── pyvenv.cfg
+├── .python-version
 ├── README.md
 ├── hello.py
 ├── pyproject.toml
@@ -81,6 +83,11 @@ description or license. You can edit this file manually, or use commands like `u
 You'll also use this file to specify uv [configuration options](../configuration/files.md) in a
 [`[tool.uv]`](../reference/settings.md) section.
 
+### `.python-version`
+
+The `.python-version` file contains the project's default Python version. This file tells uv which
+Python version to use when creating the project's virtual environment.
+
 ### `.venv`
 
 The `.venv` folder contains your project's virtual environment, a Python environment that is