Use prettier to format the documentation (#5708)

To enforce the 100 character line limit in markdown files introduced in
https://github.com/astral-sh/uv/pull/5635, and to automate the
formatting of markdown files, i've added prettier and formatted our
markdown files with it.

I've excluded the changelog and the generated references documentation
from this for having too many changes, but we can also include them.

I'm not particular on which style we use. My main motivations are
(major) not having to reflow markdown files myself anymore and (minor)
consistence between all markdown files. I've chosen prettier for similar
reason as we chose black, it's a single good style that's automated and
shared in the community. I do prefer prettier's style of not breaking
inside of a link name though.

This PR is in two parts, the first adds prettier to CI and documents
using it, while the second actually formats the docs. When merge
conflicts arise, we can drop the last commit and regenerate it with `npx
prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md
README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md
docs/pip/**/*.md`.

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
This commit is contained in:
konsti
2024-08-02 15:58:31 +02:00
committed by GitHub
parent f2c4b9c752
commit db371560bc
42 changed files with 711 additions and 646 deletions

View File

@@ -1,20 +1,20 @@
# Python versions
A Python version is composed of a Python interpreter (i.e. the `python` executable), the standard
library, and other supporting files.
library, and other supporting files.
## Managed and system Python installations
Since it is common for a system to have an existing Python installation, uv supports
[discovering](#discovery-of-python-versions) Python versions. However, uv also supports [installing
Python versions](#installing-a-python-version) itself. To distinguish between these two types of
Python installations, uv refers to Python versions it installs as _managed_ Python installations and
all other Python installations as _system_ Python installations.
[discovering](#discovery-of-python-versions) Python versions. However, uv also supports
[installing Python versions](#installing-a-python-version) itself. To distinguish between these two
types of Python installations, uv refers to Python versions it installs as _managed_ Python
installations and all other Python installations as _system_ Python installations.
!!! note
uv does not distinguish between Python versions installed by the operating system vs those
installed and managed by other tools. For example, if a Python installation is managed with
installed and managed by other tools. For example, if a Python installation is managed with
`pyenv`, it would still be considered a _system_ Python version in uv.
## Requesting a version
@@ -46,8 +46,8 @@ Additionally, a specific system Python interpreter can be requested with:
- `<install-dir>` e.g. `/some/environment/`
By default, uv will automatically download Python versions if they cannot be found on the system.
This behavior can be [disabled with the `python-fetch`
option](#disabling-automatic-python-downloads).
This behavior can be
[disabled with the `python-fetch` option](#disabling-automatic-python-downloads).
## Installing a Python version
@@ -130,8 +130,8 @@ uv python list --only-installed
When searching for a Python version, the following locations are checked:
- Managed Python installations in the `UV_PYTHON_INSTALL_DIR`.
- A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or `python.exe`
on Windows.
- A Python interpreter on the `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or
`python.exe` on Windows.
- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version.
@@ -152,7 +152,7 @@ The `python-fetch` option can be used to disable this behavior. By default, it i
## Adjusting Python version preferences
By default, uv will attempt to use Python versions found on the system and only download managed
interpreters when necessary.
interpreters when necessary.
The `python-preference` option can be used to adjust this behavior. By default, it is set to
`managed` which prefers managed Python installations over system Python installations. However,
@@ -161,8 +161,8 @@ system Python installations are still preferred over downloading a managed Pytho
The following alternative options are available:
- `only-managed`: Only use managed Python installations; never use system Python installations
- `system`: Prefer system Python installations over managed Python installations
- `only-system`: Only use system Python installations; never use managed Python installations
- `system`: Prefer system Python installations over managed Python installations
- `only-system`: Only use system Python installations; never use managed Python installations
These options allow disabling uv's managed Python versions entirely or always using them and
ignoring any existing system installations.
@@ -199,14 +199,13 @@ distributions from the
[`python-build-standalone`](https://github.com/indygreg/python-build-standalone) project. The
project is partially maintained by the uv maintainers and is used by many other Python projects.
The uv Python distributions are self-contained, highly-portable, and performant. While
Python can be built from source, as in tools like `pyenv`, it requires preinstalled system
dependencies and creating optimized, performant builds is very slow.
The uv Python distributions are self-contained, highly-portable, and performant. While Python can be
built from source, as in tools like `pyenv`, it requires preinstalled system dependencies and
creating optimized, performant builds is very slow.
These distributions have some behavior quirks, generally as a consequence of portability. See the
[`python-build-standalone`
quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for
details.
[`python-build-standalone` quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html)
documentation for details.
### PyPy distributions