From fd17f6d9029abc480b1a4a438caa6882a24bc9c8 Mon Sep 17 00:00:00 2001 From: Mathieu Kniewallner Date: Tue, 27 Aug 2024 13:05:14 +0200 Subject: [PATCH] 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. --- docs/concepts/resolution.md | 6 ++-- docs/configuration/files.md | 2 +- docs/getting-started/installation.md | 48 +++++++++++++++++----------- docs/guides/integration/github.md | 8 ++--- docs/index.md | 16 ++++++---- docs/pip/compatibility.md | 11 ++++--- docs/pip/compile.md | 4 +-- docs/pip/dependencies.md | 2 +- docs/pip/environments.md | 16 ++++++---- docs/reference/resolver-internals.md | 4 +-- 10 files changed, 69 insertions(+), 48 deletions(-) diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md index 57c0c1475..8ac9410c9 100644 --- a/docs/concepts/resolution.md +++ b/docs/concepts/resolution.md @@ -154,13 +154,13 @@ other dependencies. uv will always use the latest versions for build dependencie For example, given the following `requirements.in` file: -```text title="requirements.in" +```python title="requirements.in" flask>=2.0.0 ``` 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: # uv pip compile requirements.in blinker==1.7.0 @@ -182,7 +182,7 @@ werkzeug==3.0.1 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: # uv pip compile requirements.in --resolution lowest click==7.1.2 diff --git a/docs/configuration/files.md b/docs/configuration/files.md index af88232a6..c76c4e025 100644 --- a/docs/configuration/files.md +++ b/docs/configuration/files.md @@ -18,7 +18,7 @@ all members. 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`: -```toml title="project.toml" +```toml title="pyproject.toml" [tool.uv.pip] index-url = "https://test.pypi.org/simple" ``` diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 6f8cefe3e..035987157 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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: -```console title="macOS and Linux" -$ curl -LsSf https://astral.sh/uv/install.sh | sh -``` +=== "macOS and Linux" -```console title="Windows" -$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` + ```console + $ 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`. @@ -22,25 +26,33 @@ By default, uv is installed to `~/.cargo/bin`. The installation script may be inspected before use: - ```console title="macOS and Linux" - $ curl -LsSf https://astral.sh/uv/install.sh | less - ``` + === "macOS and Linux" - ```console title="Windows" - $ powershell -c "irm https://astral.sh/uv/install.ps1 | more" - ``` + ```console + $ 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). Request a specific version by including it in the URL: -```console title="macOS and Linux" -$ curl -LsSf https://astral.sh/uv/0.3.4/install.sh | sh -``` +=== "macOS and Linux" -```console title="Windows" -$ powershell -c "irm https://astral.sh/uv/0.3.4/install.ps1 | iex" -``` + ```console + $ 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 diff --git a/docs/guides/integration/github.md b/docs/guides/integration/github.md index 13b6b06e9..3bda10478 100644 --- a/docs/guides/integration/github.md +++ b/docs/guides/integration/github.md @@ -4,10 +4,10 @@ uv installation differs depending on the platform: -=== "Unix" +=== "Linux" ```yaml title="example.yml" - name: Example on Unix + name: Example on Linux jobs: 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: -=== "Unix" +=== "Linux" ```yaml title="example.yml" - name: Example on Unix + name: Example on Linux jobs: uv-example-linux: diff --git a/docs/index.md b/docs/index.md index b5e975065..3172a6798 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,13 +38,17 @@ uv is backed by [Astral](https://astral.sh), the creators of Install uv with our official standalone installer: -```console title="macOS and Linux" -$ curl -LsSf https://astral.sh/uv/install.sh | sh -``` +=== "macOS and Linux" -```console title="Windows" -$ powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` + ```console + $ 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. diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 217221123..4269035cb 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -225,7 +225,7 @@ _should_ be equally valid. For example, consider: -```text title="requirements.txt" +```python title="requirements.in" starlette 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 falling back to `fastapi==0.1.17`: -```text +```python title="requirements.txt" # This file was autogenerated by uv via the following command: -# uv pip compile - +# uv pip compile requirements.in annotated-types==0.6.0 # via pydantic 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 requires falling back to `starlette==0.36.3`: -```text -# uv pip compile - +```python title="requirements.txt" +# This file was autogenerated by uv via the following command: +# uv pip compile requirements.in annotated-types==0.6.0 # via pydantic anyio==4.3.0 diff --git a/docs/pip/compile.md b/docs/pip/compile.md index 312a56205..8bb261405 100644 --- a/docs/pip/compile.md +++ b/docs/pip/compile.md @@ -113,7 +113,7 @@ dependencies of the current project. To define a constraint, define a bound for a package: -```text title="constraints.txt" +```python title="constraints.txt" 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: -```text title="overrides.txt" +```python title="overrides.txt" c>=2.0 ``` diff --git a/docs/pip/dependencies.md b/docs/pip/dependencies.md index 3259be8d3..0ee3ae477 100644 --- a/docs/pip/dependencies.md +++ b/docs/pip/dependencies.md @@ -45,7 +45,7 @@ dependencies. To define dependencies in a `requirements.in` file: -```text title="requirements.in" +```python title="requirements.in" httpx ruff>=0.3.0 ``` diff --git a/docs/pip/environments.md b/docs/pip/environments.md index 6cf555372..906048f61 100644 --- a/docs/pip/environments.md +++ b/docs/pip/environments.md @@ -45,13 +45,17 @@ $ uv pip install ruff The virtual environment can be "activated" to make its packages available: -```console title="macOS and Linux" -$ source .venv/bin/activate -``` +=== "macOS and Linux" -```console title="Windows" -$ .venv\Scripts\activate -``` + ```console + $ source .venv/bin/activate + ``` + +=== "Windows" + + ```console + $ .venv\Scripts\activate + ``` ## Using arbitrary Python environments diff --git a/docs/reference/resolver-internals.md b/docs/reference/resolver-internals.md index 18891d59d..820b1db8f 100644 --- a/docs/reference/resolver-internals.md +++ b/docs/reference/resolver-internals.md @@ -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 environments, for example: -```text +```python numpy>=2,<3 ; 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 — there can be many forks per package. For example, given: -```text +```python flask > 1 ; sys_platform == 'darwin' flask > 2 ; sys_platform == 'win32' flask