docs: use python to highlight requirements and use more content tabs (#6549)

## Summary

It appears that using `python` for code blocks containing requirements
works quite well.

![Screenshot from 2024-08-23
23-23-05](https://github.com/user-attachments/assets/38c92ef7-1f5e-40eb-8ea4-7024c8180bc4)

![Screenshot from 2024-08-23
23-23-31](https://github.com/user-attachments/assets/940dc7d5-22a8-4cd8-b54a-d56542d4345c)

Also using more content tabs for cases where we need to differentiate
macOS/Linux from Windows.

## Test Plan

Local run of the documentation.
This commit is contained in:
Mathieu Kniewallner 2024-08-27 13:05:14 +02:00 committed by GitHub
parent 6a988aca55
commit fd17f6d902
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 69 additions and 48 deletions

View file

@ -154,13 +154,13 @@ other dependencies. uv will always use the latest versions for build dependencie
For example, given the following `requirements.in` file: For example, given the following `requirements.in` file:
```text title="requirements.in" ```python title="requirements.in"
flask>=2.0.0 flask>=2.0.0
``` ```
Running `uv pip compile requirements.in` would produce the following `requirements.txt` file: Running `uv pip compile requirements.in` would produce the following `requirements.txt` file:
```text title="requirements.txt" ```python title="requirements.txt"
# This file was autogenerated by uv via the following command: # This file was autogenerated by uv via the following command:
# uv pip compile requirements.in # uv pip compile requirements.in
blinker==1.7.0 blinker==1.7.0
@ -182,7 +182,7 @@ werkzeug==3.0.1
However, `uv pip compile --resolution lowest requirements.in` would instead produce: However, `uv pip compile --resolution lowest requirements.in` would instead produce:
```text title="requirements.in" ```python title="requirements.in"
# This file was autogenerated by uv via the following command: # This file was autogenerated by uv via the following command:
# uv pip compile requirements.in --resolution lowest # uv pip compile requirements.in --resolution lowest
click==7.1.2 click==7.1.2

View file

@ -18,7 +18,7 @@ all members.
If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. For If a `pyproject.toml` file is found, uv will read configuration from the `[tool.uv.pip]` table. For
example, to set a persistent index URL, add the following to a `pyproject.toml`: example, to set a persistent index URL, add the following to a `pyproject.toml`:
```toml title="project.toml" ```toml title="pyproject.toml"
[tool.uv.pip] [tool.uv.pip]
index-url = "https://test.pypi.org/simple" index-url = "https://test.pypi.org/simple"
``` ```

View file

@ -8,13 +8,17 @@ Install uv with our standalone installers or your package manager of choice.
uv provides a standalone installer to download and install uv: uv provides a standalone installer to download and install uv:
```console title="macOS and Linux" === "macOS and Linux"
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```
```console title="Windows" ```console
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex" $ curl -LsSf https://astral.sh/uv/install.sh | sh
``` ```
=== "Windows"
```console
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
By default, uv is installed to `~/.cargo/bin`. By default, uv is installed to `~/.cargo/bin`.
@ -22,25 +26,33 @@ By default, uv is installed to `~/.cargo/bin`.
The installation script may be inspected before use: The installation script may be inspected before use:
```console title="macOS and Linux" === "macOS and Linux"
$ curl -LsSf https://astral.sh/uv/install.sh | less
```
```console title="Windows" ```console
$ powershell -c "irm https://astral.sh/uv/install.ps1 | more" $ curl -LsSf https://astral.sh/uv/install.sh | less
``` ```
=== "Windows"
```console
$ powershell -c "irm https://astral.sh/uv/install.ps1 | more"
```
Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases). Alternatively, the installer or binaries can be downloaded directly from [GitHub](#github-releases).
Request a specific version by including it in the URL: Request a specific version by including it in the URL:
```console title="macOS and Linux" === "macOS and Linux"
$ curl -LsSf https://astral.sh/uv/0.3.4/install.sh | sh
```
```console title="Windows" ```console
$ powershell -c "irm https://astral.sh/uv/0.3.4/install.ps1 | iex" $ curl -LsSf https://astral.sh/uv/0.3.4/install.sh | sh
``` ```
=== "Windows"
```console
$ powershell -c "irm https://astral.sh/uv/0.3.4/install.ps1 | iex"
```
### PyPI ### PyPI

View file

@ -4,10 +4,10 @@
uv installation differs depending on the platform: uv installation differs depending on the platform:
=== "Unix" === "Linux"
```yaml title="example.yml" ```yaml title="example.yml"
name: Example on Unix name: Example on Linux
jobs: jobs:
uv-example-linux: uv-example-linux:
@ -61,10 +61,10 @@ uv installation differs depending on the platform:
It is considered best practice to pin to a specific uv version, e.g., with: It is considered best practice to pin to a specific uv version, e.g., with:
=== "Unix" === "Linux"
```yaml title="example.yml" ```yaml title="example.yml"
name: Example on Unix name: Example on Linux
jobs: jobs:
uv-example-linux: uv-example-linux:

View file

@ -38,13 +38,17 @@ uv is backed by [Astral](https://astral.sh), the creators of
Install uv with our official standalone installer: Install uv with our official standalone installer:
```console title="macOS and Linux" === "macOS and Linux"
$ curl -LsSf https://astral.sh/uv/install.sh | sh
```
```console title="Windows" ```console
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex" $ curl -LsSf https://astral.sh/uv/install.sh | sh
``` ```
=== "Windows"
```console
$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Then, check out the [first steps](./getting-started/first-steps.md) or read on for a brief overview. Then, check out the [first steps](./getting-started/first-steps.md) or read on for a brief overview.

View file

@ -225,7 +225,7 @@ _should_ be equally valid.
For example, consider: For example, consider:
```text title="requirements.txt" ```python title="requirements.in"
starlette starlette
fastapi fastapi
``` ```
@ -238,9 +238,9 @@ If a resolver prioritizes including the most recent version of `starlette`, it w
older version of `fastapi` that excludes the upper bound on `starlette`. In practice, this requires older version of `fastapi` that excludes the upper bound on `starlette`. In practice, this requires
falling back to `fastapi==0.1.17`: falling back to `fastapi==0.1.17`:
```text ```python title="requirements.txt"
# This file was autogenerated by uv via the following command: # This file was autogenerated by uv via the following command:
# uv pip compile - # uv pip compile requirements.in
annotated-types==0.6.0 annotated-types==0.6.0
# via pydantic # via pydantic
anyio==4.3.0 anyio==4.3.0
@ -266,8 +266,9 @@ Alternatively, if a resolver prioritizes including the most recent version of `f
need to use an older version of `starlette` that satisfies the upper bound. In practice, this need to use an older version of `starlette` that satisfies the upper bound. In practice, this
requires falling back to `starlette==0.36.3`: requires falling back to `starlette==0.36.3`:
```text ```python title="requirements.txt"
# uv pip compile - # This file was autogenerated by uv via the following command:
# uv pip compile requirements.in
annotated-types==0.6.0 annotated-types==0.6.0
# via pydantic # via pydantic
anyio==4.3.0 anyio==4.3.0

View file

@ -113,7 +113,7 @@ dependencies of the current project.
To define a constraint, define a bound for a package: To define a constraint, define a bound for a package:
```text title="constraints.txt" ```python title="constraints.txt"
pydantic<2.0 pydantic<2.0
``` ```
@ -141,7 +141,7 @@ then the dependencies cannot be resolved.
To define an override, define the new requirement for the problematic package: To define an override, define the new requirement for the problematic package:
```text title="overrides.txt" ```python title="overrides.txt"
c>=2.0 c>=2.0
``` ```

View file

@ -45,7 +45,7 @@ dependencies.
To define dependencies in a `requirements.in` file: To define dependencies in a `requirements.in` file:
```text title="requirements.in" ```python title="requirements.in"
httpx httpx
ruff>=0.3.0 ruff>=0.3.0
``` ```

View file

@ -45,13 +45,17 @@ $ uv pip install ruff
The virtual environment can be "activated" to make its packages available: The virtual environment can be "activated" to make its packages available:
```console title="macOS and Linux" === "macOS and Linux"
$ source .venv/bin/activate
```
```console title="Windows" ```console
$ .venv\Scripts\activate $ source .venv/bin/activate
``` ```
=== "Windows"
```console
$ .venv\Scripts\activate
```
## Using arbitrary Python environments ## Using arbitrary Python environments

View file

@ -70,7 +70,7 @@ was usually limited to single environment, which one specific architecture, oper
version, and Python implementation. Some packages use contradictory requirements for different version, and Python implementation. Some packages use contradictory requirements for different
environments, for example: environments, for example:
```text ```python
numpy>=2,<3 ; python_version >= "3.11" numpy>=2,<3 ; python_version >= "3.11"
numpy>=1.16,<2 ; python_version < "3.11" numpy>=1.16,<2 ; python_version < "3.11"
``` ```
@ -85,7 +85,7 @@ In the above example, the partial solution would be split into two resolutions,
If markers overlap or are missing a part of the marker space, the resolver splits additional times — If markers overlap or are missing a part of the marker space, the resolver splits additional times —
there can be many forks per package. For example, given: there can be many forks per package. For example, given:
```text ```python
flask > 1 ; sys_platform == 'darwin' flask > 1 ; sys_platform == 'darwin'
flask > 2 ; sys_platform == 'win32' flask > 2 ; sys_platform == 'win32'
flask flask