From e61a221fef5593ff103a95170b99fa1862672c48 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Mon, 15 Jul 2024 18:22:07 -0400 Subject: [PATCH] Migrate from MdBook to MkDocs (#5062) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary We want to have consistency between the Ruff and uv documentation for the upcoming release. We don't love the Ruff docs, but we'd rather have consistency and then work towards improving them both, rather than have two very-different documentation sites that both have weaknesses. The setup here is simpler than in Ruff as: (1) we don't yet generate any docs from Rust and (2) we don't try to reuse the README in the uv documentation (which adds a lot of complexity in Ruff). So the change here is mostly a 1-to-1 port to MkDocs. ## Test Plan ![Screenshot 2024-07-14 at 9 49 15 PM](https://github.com/user-attachments/assets/8bfb5b06-08ff-4329-b368-d9087b78996e) --- .github/workflows/docs.yml | 49 ------- .github/workflows/publish-docs.yml | 50 +++++++ .../integrations/analytics/fathom.html | 1 + docs/README.md | 21 --- docs/SUMMARY.md | 51 ------- docs/{theme => assets}/favicon.ico | Bin docs/{theme => assets}/favicon.svg | 0 docs/book.toml | 9 -- docs/configuration/authentication.md | 2 +- docs/first-steps.md | 2 +- docs/guides/install-python.md | 4 +- docs/{introduction.md => index.md} | 14 +- docs/pip/compatibility.md | 2 +- docs/pip/environments.md | 6 +- docs/preview/introduction.md | 9 -- docs/preview/projects.md | 0 docs/python.md | 1 - docs/requirements-insiders.in | 7 + docs/requirements-insiders.txt | 124 +++++++++++++++++ docs/requirements.in | 7 + docs/requirements.txt | 128 ++++++++++++++++++ docs/resolution.md | 2 +- docs/style.css | 44 ------ docs/stylesheets/extra.css | 105 ++++++++++++++ mkdocs.insiders.yml | 1 + mkdocs.public.yml | 4 + mkdocs.template.yml | 105 ++++++++++++++ 27 files changed, 548 insertions(+), 200 deletions(-) delete mode 100644 .github/workflows/docs.yml create mode 100644 .github/workflows/publish-docs.yml create mode 100644 docs/.overrides/partials/integrations/analytics/fathom.html delete mode 100644 docs/README.md delete mode 100644 docs/SUMMARY.md rename docs/{theme => assets}/favicon.ico (100%) rename docs/{theme => assets}/favicon.svg (100%) delete mode 100644 docs/book.toml rename docs/{introduction.md => index.md} (85%) delete mode 100644 docs/preview/introduction.md create mode 100644 docs/preview/projects.md create mode 100644 docs/requirements-insiders.in create mode 100644 docs/requirements-insiders.txt create mode 100644 docs/requirements.in create mode 100644 docs/requirements.txt delete mode 100644 docs/style.css create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.insiders.yml create mode 100644 mkdocs.public.yml create mode 100644 mkdocs.template.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index be0027786..000000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,49 +0,0 @@ -name: Publish documentation - -on: - push: - branches: ["main"] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "docs" - cancel-in-progress: false - -jobs: - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Install latest mdbook - run: | - tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name') - url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz" - mkdir mdbook - curl -sSL $url | tar -xz --directory=./mdbook - echo `pwd`/mdbook >> $GITHUB_PATH - - name: Build mdbook - run: | - mdbook build docs - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - path: "docs/book" - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 000000000..85549e322 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,50 @@ +# Publish the uv documentation. +# +# Assumed to run as a subworkflow of .github/workflows/release.yml; specifically, as a post-announce +# job within `cargo-dist`. +name: mkdocs + +on: + workflow_dispatch: + inputs: + ref: + description: "The commit SHA, tag, or branch to publish. Uses the default branch if not specified." + default: "" + type: string + +jobs: + mkdocs: + runs-on: ubuntu-latest + env: + CF_API_TOKEN_EXISTS: ${{ secrets.CF_API_TOKEN != '' }} + MKDOCS_INSIDERS_SSH_KEY_EXISTS: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY != '' }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ inputs.ref }} + - uses: actions/setup-python@v5 + - name: "Add SSH key" + if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }} + uses: webfactory/ssh-agent@v0.9.0 + with: + ssh-private-key: ${{ secrets.MKDOCS_INSIDERS_SSH_KEY }} + - name: "Install Insiders dependencies" + if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }} + run: pip install -r docs/requirements-insiders.txt + - name: "Install dependencies" + if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }} + run: pip install -r docs/requirements.txt + - name: "Build Insiders docs" + if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS == 'true' }} + run: mkdocs build --strict -f mkdocs.insiders.yml + - name: "Build docs" + if: ${{ env.MKDOCS_INSIDERS_SSH_KEY_EXISTS != 'true' }} + run: mkdocs build --strict -f mkdocs.public.yml + - name: "Deploy to Cloudflare Pages" + if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }} + uses: cloudflare/wrangler-action@v3.7.0 + with: + apiToken: ${{ secrets.CF_API_TOKEN }} + accountId: ${{ secrets.CF_ACCOUNT_ID }} + # `github.head_ref` is only set during pull requests and for manual runs or tags we use `main` to deploy to production + command: pages deploy site --project-name=uv-docs --branch ${{ github.head_ref || 'main' }} --commit-hash ${GITHUB_SHA} diff --git a/docs/.overrides/partials/integrations/analytics/fathom.html b/docs/.overrides/partials/integrations/analytics/fathom.html new file mode 100644 index 000000000..1bb6e52d3 --- /dev/null +++ b/docs/.overrides/partials/integrations/analytics/fathom.html @@ -0,0 +1 @@ + diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index fd16ef289..000000000 --- a/docs/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Documentation - -This is the home of the new documentation for uv. - -The documentation is a work in progress and not ready for external references. - -## Contributing - -Install mdbook: - -``` -cargo install mdbook -``` - -To run the documentation locally: - -``` -mdbook watch docs --open -``` - -The documentation is published to GitHub Pages on merge to `main`. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index e3869cb0b..000000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,51 +0,0 @@ -# Summary - -- [Introduction](introduction.md) - -# Getting started - -- [Installing uv](installation.md) -- [First steps](first-steps.md) - -# Guides - -- [Installing Python](guides/install-python.md) -- [Running scripts](guides/scripts.md) -- [Using tools](guides/tools.md) -- [Creating a project](guides/projects.md) - -# Concepts - -- [Projects](preview/projects.md) -- [Command-line tools](preview/tools.md) -- [Python versions](python-versions.md) -- [Workspaces](preview/workspaces.md) -- [Dependency sources](preview/dependencies.md) -- [Resolution](resolution.md) -- [Caching](cache.md) -- [Authentication](configuration/authentication.md) - -# Configuration - -- [Configuration files](configuration/files.md) -- [Environment variables](configuration/environment.md) - -# Integration guides - -- [Using in Docker](guides/docker.md) -- [Using in GitHub Actions](guides/github.md) -- [Using in pre-commit](guides/pre-commit.md) - -# Low-level operations - -- [Using environments](pip/environments.md) -- [Managing packages](pip/packages.md) -- [Inspecting packages](pip/inspection.md) -- [Declaring dependencies](pip/dependencies.md) -- [Locking environments](pip/compile.md) - -# Policies - -- [Versioning](versioning.md) -- [Platform support](platforms.md) -- [Compatibility with pip](pip/compatibility.md) diff --git a/docs/theme/favicon.ico b/docs/assets/favicon.ico similarity index 100% rename from docs/theme/favicon.ico rename to docs/assets/favicon.ico diff --git a/docs/theme/favicon.svg b/docs/assets/favicon.svg similarity index 100% rename from docs/theme/favicon.svg rename to docs/assets/favicon.svg diff --git a/docs/book.toml b/docs/book.toml deleted file mode 100644 index c0832dca1..000000000 --- a/docs/book.toml +++ /dev/null @@ -1,9 +0,0 @@ -[book] -language = "en" -multilingual = false -src = "." -title = "uv" - -[output.html] -no-section-label = true -additional-css = ["style.css"] diff --git a/docs/configuration/authentication.md b/docs/configuration/authentication.md index a5d89c2f1..b6bb4f2c2 100644 --- a/docs/configuration/authentication.md +++ b/docs/configuration/authentication.md @@ -46,7 +46,7 @@ Authentication may be used for hosts specified in the following contexts: - `find-links` - `package @ https://...` -See the [`pip` compatibility guide](./pip/compatibility.md#registry-authentication) for details on differences from +See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on differences from `pip`. ## Custom CA certificates diff --git a/docs/first-steps.md b/docs/first-steps.md index 2cfe9c983..bdd8e18cc 100644 --- a/docs/first-steps.md +++ b/docs/first-steps.md @@ -33,7 +33,7 @@ These commands are used to manage Python itself. uv is capable of installing and - `uv python list` - `uv python find` -See the documentation on [toolchains](./preview/toolchains.md) for more details on getting started. +See the documentation on [toolchains](./python-versions.md) for more details on getting started. ### Command-line tool management diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md index ee9edf3cc..10dbbdab7 100644 --- a/docs/guides/install-python.md +++ b/docs/guides/install-python.md @@ -36,7 +36,7 @@ To view available and installed Python versions: $ uv python list ``` -See the [`python list`](../python-versions.html#viewing-available-python-versions) documentation for more details. +See the [`python list`](../python-versions.md#viewing-available-python-versions) documentation for more details. @@ -62,4 +62,4 @@ uv will also use an existing Python installation if already present on the syste To force uv to use the system Python, provide the `--python-preference only-system` option. -See the [Python version preference](../python-versions.html#adjusting-python-version-preferences) documentation for more details. +See the [Python version preference](../python-versions.md#adjusting-python-version-preferences) documentation for more details. diff --git a/docs/introduction.md b/docs/index.md similarity index 85% rename from docs/introduction.md rename to docs/index.md index cd179b1f7..e26dfa766 100644 --- a/docs/introduction.md +++ b/docs/index.md @@ -9,11 +9,11 @@ An extremely fast Python package installer and resolver, written in Rust. Design replacement for common `pip` and `pip-tools` workflows.

- - - - Shows a bar chart with benchmark results. - + Shows a bar chart with benchmark results. +

+ +

+ Shows a bar chart with benchmark results.

@@ -53,14 +53,14 @@ powershell -c "irm https://astral.sh/uv/install.ps1 | iex" Or, see our [installation guide](./installation.md) for more options. -Then, check out our documentation [creating an environment](pip/environments.html). +Then, check out our documentation [creating an environment](pip/environments.md). ## Features uv supports features familiar from `pip` and `pip-tools`: - [Managing Python environments](pip/environments.md) -- [Installing packages](pip/basics.md) +- [Installing packages](pip/packages.md) - [Inspecting packages](pip/inspection.md) - [Locking environments](pip/compile.md) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 0eab39404..084cad961 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -183,7 +183,7 @@ In other words, uv inverts the default, requiring explicit opt-in to installing Python, which can lead to breakages and other complications, and should only be done in limited circumstances. -For more, see ["Installing into arbitrary Python environments"](./README.md#installing-into-arbitrary-python-environments). +For more, see ["Using arbitrary Python environments"](./environments.md#using-arbitrary-python-environments). ## Resolution strategy diff --git a/docs/pip/environments.md b/docs/pip/environments.md index 10a5cac8d..23227b132 100644 --- a/docs/pip/environments.md +++ b/docs/pip/environments.md @@ -26,8 +26,8 @@ uv venv --python 3.11 ``` Note this requires the requested Python version to be available on the system. -However, in preview mode, [uv will download Python for you](../preview/toolchains.md). -See the [python request](../python/requests.md) documentation for more details on requesting Python versions. +However, in preview mode, [uv will download Python for you](../python-versions.md). +See the [Python request](../python.md) documentation for more details on requesting Python versions. ## Using a virtual environment @@ -115,4 +115,4 @@ If a specific Python version is requested, e.g., `--python 3.7`, additional exec When running a command that does not mutate the environment such as `uv pip compile`, uv does not _require_ a virtual environment. Instead, it needs a Python toolchain to create ephemeral environments. -See the documentation on [toolchain discovery](./preview/toolchains.md#discovery-order) for details on discovery. +See the documentation on [toolchain discovery](../python-versions.md#discovery-order) for details on discovery. diff --git a/docs/preview/introduction.md b/docs/preview/introduction.md deleted file mode 100644 index 108376bcd..000000000 --- a/docs/preview/introduction.md +++ /dev/null @@ -1,9 +0,0 @@ -# Introduction - -uv is expanding from low-level commands to manage virtual environments and their packages to high-level project management commands and global management of Python installations and command line tools. - -See the [project documentation](projects.md) for using uv to manage dependencies in a project, similar to `poetry`. - -See the [tool documentation](tools.md) for using uv to run tools in ephemeral environments and install tools, similar to `pipx`. - -See the [toolchain documentation](toolchains.md) for using uv to manage Python installations, similar to `pyenv`. diff --git a/docs/preview/projects.md b/docs/preview/projects.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/python.md b/docs/python.md index ffdbbabea..e69de29bb 100644 --- a/docs/python.md +++ b/docs/python.md @@ -1 +0,0 @@ -# Python environments diff --git a/docs/requirements-insiders.in b/docs/requirements-insiders.in new file mode 100644 index 000000000..26f415139 --- /dev/null +++ b/docs/requirements-insiders.in @@ -0,0 +1,7 @@ +black>=23.10.0 +mkdocs>=1.5.0 +mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4 +mkdocs-redirects>=1.2.1 +mdformat>=0.7.17 +mdformat-mkdocs>=2.0.4 +mdformat-admon>=2.0.2 diff --git a/docs/requirements-insiders.txt b/docs/requirements-insiders.txt new file mode 100644 index 000000000..363030281 --- /dev/null +++ b/docs/requirements-insiders.txt @@ -0,0 +1,124 @@ +# This file was autogenerated by uv via the following command: +# uv pip compile docs/requirements-insiders.in -o docs/requirements-insiders.txt --universal -p 3.12 +babel==2.15.0 + # via mkdocs-material +black==23.10.0 + # via -r docs/requirements-insiders.in +certifi==2024.7.4 + # via requests +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via + # black + # mkdocs +colorama==0.4.6 + # via + # click + # mkdocs + # mkdocs-material +ghp-import==2.1.0 + # via mkdocs +idna==3.7 + # via requests +jinja2==3.1.4 + # via + # mkdocs + # mkdocs-material +linkify-it-py==2.0.3 + # via markdown-it-py +markdown==3.6 + # via + # mkdocs + # mkdocs-material + # pymdown-extensions +markdown-it-py==3.0.0 + # via + # mdformat + # mdformat-gfm + # mdit-py-plugins +markupsafe==2.1.5 + # via + # jinja2 + # mkdocs +mdformat==0.7.17 + # via + # -r docs/requirements-insiders.in + # mdformat-admon + # mdformat-gfm + # mdformat-mkdocs + # mdformat-tables +mdformat-admon==2.0.2 + # via + # -r docs/requirements-insiders.in + # mdformat-mkdocs +mdformat-gfm==0.3.6 + # via mdformat-mkdocs +mdformat-mkdocs==2.0.4 + # via -r docs/requirements-insiders.in +mdformat-tables==0.4.1 + # via mdformat-gfm +mdit-py-plugins==0.4.1 + # via + # mdformat-admon + # mdformat-gfm +mdurl==0.1.2 + # via markdown-it-py +mergedeep==1.3.4 + # via + # mkdocs + # mkdocs-material +mkdocs==1.5.0 + # via + # -r docs/requirements-insiders.in + # mkdocs-material + # mkdocs-redirects +mkdocs-material @ git+ssh://git@github.com/astral-sh/mkdocs-material-insiders.git@38c0b8187325c3bab386b666daf3518ac036f2f4 + # via -r docs/requirements-insiders.in +mkdocs-material-extensions==1.3.1 + # via mkdocs-material +mkdocs-redirects==1.2.1 + # via -r docs/requirements-insiders.in +more-itertools==10.3.0 + # via mdformat-mkdocs +mypy-extensions==1.0.0 + # via black +packaging==24.1 + # via + # black + # mkdocs +paginate==0.5.6 + # via mkdocs-material +pathspec==0.12.1 + # via + # black + # mkdocs +platformdirs==4.2.2 + # via + # black + # mkdocs +pygments==2.18.0 + # via mkdocs-material +pymdown-extensions==10.8.1 + # via mkdocs-material +python-dateutil==2.9.0.post0 + # via ghp-import +pyyaml==6.0.1 + # via + # mkdocs + # pymdown-extensions + # pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs +regex==2022.10.31 + # via mkdocs-material +requests==2.32.3 + # via mkdocs-material +six==1.16.0 + # via python-dateutil +uc-micro-py==1.0.3 + # via linkify-it-py +urllib3==2.2.2 + # via requests +watchdog==4.0.1 + # via mkdocs diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 000000000..9aea93dcf --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,7 @@ +black>=23.10.0 +mkdocs>=1.5.0 +mkdocs-material>=9.1.18 +mkdocs-redirects>=1.2.1 +mdformat>=0.7.17 +mdformat-mkdocs>=2.0.4 +mdformat-admon>=2.0.2 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..8b7a8cee9 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,128 @@ +# This file was autogenerated by uv via the following command: +# uv pip compile docs/requirements.in -o docs/requirements.txt --universal -p 3.12 +babel==2.15.0 + # via mkdocs-material +black==24.4.2 + # via -r docs/requirements.in +certifi==2024.7.4 + # via requests +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via + # black + # mkdocs +colorama==0.4.6 + # via + # click + # mkdocs + # mkdocs-material +ghp-import==2.1.0 + # via mkdocs +idna==3.7 + # via requests +jinja2==3.1.4 + # via + # mkdocs + # mkdocs-material +linkify-it-py==2.0.3 + # via markdown-it-py +markdown==3.6 + # via + # mkdocs + # mkdocs-material + # pymdown-extensions +markdown-it-py==3.0.0 + # via + # mdformat + # mdformat-gfm + # mdit-py-plugins +markupsafe==2.1.5 + # via + # jinja2 + # mkdocs +mdformat==0.7.17 + # via + # -r docs/requirements.in + # mdformat-admon + # mdformat-gfm + # mdformat-mkdocs + # mdformat-tables +mdformat-admon==2.0.6 + # via + # -r docs/requirements.in + # mdformat-mkdocs +mdformat-gfm==0.3.6 + # via mdformat-mkdocs +mdformat-mkdocs==3.0.0 + # via -r docs/requirements.in +mdformat-tables==0.4.1 + # via mdformat-gfm +mdit-py-plugins==0.4.1 + # via + # mdformat-admon + # mdformat-gfm + # mdformat-mkdocs +mdurl==0.1.2 + # via markdown-it-py +mergedeep==1.3.4 + # via + # mkdocs + # mkdocs-get-deps +mkdocs==1.6.0 + # via + # -r docs/requirements.in + # mkdocs-material + # mkdocs-redirects +mkdocs-get-deps==0.2.0 + # via mkdocs +mkdocs-material==9.5.29 + # via -r docs/requirements.in +mkdocs-material-extensions==1.3.1 + # via mkdocs-material +mkdocs-redirects==1.2.1 + # via -r docs/requirements.in +more-itertools==10.3.0 + # via mdformat-mkdocs +mypy-extensions==1.0.0 + # via black +packaging==24.1 + # via + # black + # mkdocs +paginate==0.5.6 + # via mkdocs-material +pathspec==0.12.1 + # via + # black + # mkdocs +platformdirs==4.2.2 + # via + # black + # mkdocs-get-deps +pygments==2.18.0 + # via mkdocs-material +pymdown-extensions==10.8.1 + # via mkdocs-material +python-dateutil==2.9.0.post0 + # via ghp-import +pyyaml==6.0.1 + # via + # mkdocs + # mkdocs-get-deps + # pymdown-extensions + # pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs +regex==2024.5.15 + # via mkdocs-material +requests==2.32.3 + # via mkdocs-material +six==1.16.0 + # via python-dateutil +uc-micro-py==1.0.3 + # via linkify-it-py +urllib3==2.2.2 + # via requests +watchdog==4.0.1 + # via mkdocs diff --git a/docs/resolution.md b/docs/resolution.md index 385d3fb64..3dcc7077e 100644 --- a/docs/resolution.md +++ b/docs/resolution.md @@ -80,7 +80,7 @@ to model, and are a frequent source of bugs in other packaging tools. uv's pre-r is _intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure correctness. -For more, see ["Pre-release compatibility"](./PIP_COMPATIBILITY.md#pre-release-compatibility) +For more, see ["Pre-release compatibility"](./pip/compatibility.md#pre-release-compatibility) ## Dependency overrides diff --git a/docs/style.css b/docs/style.css deleted file mode 100644 index 9e734c07a..000000000 --- a/docs/style.css +++ /dev/null @@ -1,44 +0,0 @@ -/* Improve the font rendering */ -html { - font-family: -apple-system, BlinkMacSystemFont, Inter, Segoe UI, Helvetica Neue, sans-serif; -} -.heading, a, code, kbd, li, p, span, td { - -webkit-font-smoothing: antialiased; -} - -/* Improve padding and display of the navbar */ -.chapter { - padding-inline-start: 1.2rem; -} -.chapter li.chapter-item { - margin-left: 1em; - margin-block-start: 0.2em; - font-weight: 300; - margin-block-end: 0.4em; - line-height: 1.2em; - font-size: 1.05em; -} -.chapter li.chapter-item a:hover { - text-decoration: underline; -} -.chapter li.part-title { - margin: 0 0 0 0; - font-weight: 500; - font-size: 1.3em; -} - -/* Special case the landing page in the navbar */ -.chapter li.chapter-item:first-child { - margin-left: 0; - font-size: 16px -} - -/* Hide the global title, it doesn't look good */ -.menu-title { - visibility: hidden; -} - -/* Reduce spacing between sections in content */ -h2, h3 { - margin-block-start: 1.2em; -} diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 000000000..f22129ecb --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,105 @@ +:root { + --black: #261230; + --white: #ffffff; + --radiate: #d7ff64; + --flare: #6340ac; + --rock: #78876e; + --galaxy: #261230; + --space: #30173d; + --comet: #6f5d6f; + --cosmic: #de5fe9; + --sun: #ffac2f; + --electron: #46ebe1; + --aurora: #46eb74; + --constellation: #5f6de9; + --neutron: #cff3cf; + --proton: #f6afbc; + --nebula: #cdcbfb; + --supernova: #f1aff6; + --starlight: #f4f4f1; + --lunar: #fbf2fc; + --asteroid: #e3cee3; + --crater: #f0dfdf; +} + +[data-md-color-scheme="astral-light"] { + --md-default-bg-color--dark: var(--black); + --md-primary-fg-color: var(--galaxy); + --md-typeset-a-color: var(--flare); + --md-accent-fg-color: var(--cosmic); +} + +[data-md-color-scheme="astral-dark"] { + --md-default-bg-color: var(--galaxy); + --md-default-fg-color: var(--white); + --md-default-fg-color--light: var(--white); + --md-default-fg-color--lighter: var(--white); + --md-primary-fg-color: var(--space); + --md-primary-bg-color: var(--white); + --md-accent-fg-color: var(--cosmic); + + --md-typeset-color: var(--white); + --md-typeset-a-color: var(--radiate); + --md-typeset-mark-color: var(--sun); + + --md-code-fg-color: var(--white); + --md-code-bg-color: var(--space); + + --md-code-hl-comment-color: var(--asteroid); + --md-code-hl-punctuation-color: var(--asteroid); + --md-code-hl-generic-color: var(--supernova); + --md-code-hl-variable-color: var(--starlight); + --md-code-hl-string-color: var(--radiate); + --md-code-hl-keyword-color: var(--supernova); + --md-code-hl-operator-color: var(--supernova); + --md-code-hl-number-color: var(--electron); + --md-code-hl-special-color: var(--electron); + --md-code-hl-function-color: var(--neutron); + --md-code-hl-constant-color: var(--radiate); + --md-code-hl-name-color: var(--md-code-fg-color); + + --md-typeset-del-color: hsla(6, 90%, 60%, 0.15); + --md-typeset-ins-color: hsla(150, 90%, 44%, 0.15); + + --md-typeset-table-color: hsla(0, 0%, 100%, 0.12); + --md-typeset-table-color--light: hsla(0, 0%, 100%, 0.035); +} + +[data-md-color-scheme="astral-light"] img[src$="#only-dark"], +[data-md-color-scheme="astral-light"] img[src$="#gh-dark-mode-only"] { + display: none; /* Hide dark images in light mode */ +} + +[data-md-color-scheme="astral-light"] img[src$="#only-light"], +[data-md-color-scheme="astral-light"] img[src$="#gh-light-mode-only"] { + display: inline; /* Show light images in light mode */ +} + +[data-md-color-scheme="astral-dark"] img[src$="#only-light"], +[data-md-color-scheme="astral-dark"] img[src$="#gh-light-mode-only"] { + display: none; /* Hide light images in dark mode */ +} + +[data-md-color-scheme="astral-dark"] img[src$="#only-dark"], +[data-md-color-scheme="astral-dark"] img[src$="#gh-dark-mode-only"] { + display: inline; /* Show dark images in dark mode */ +} + +/* See: https://github.com/squidfunk/mkdocs-material/issues/175#issuecomment-616694465 */ +.md-typeset__table { + min-width: 100%; +} +.md-typeset table:not([class]) { + display: table; +} + +/* See: https://github.com/astral-sh/ruff/issues/8519 */ +[data-md-color-scheme="astral-dark"] details summary a { + color: var(--flare); +} + +/* See: https://github.com/astral-sh/ruff/issues/9046 */ +[data-md-color-scheme="astral-dark"] div.admonition { + color: var(--md-code-fg-color); + background-color: var(--md-code-bg-color); +} diff --git a/mkdocs.insiders.yml b/mkdocs.insiders.yml new file mode 100644 index 000000000..422e79d51 --- /dev/null +++ b/mkdocs.insiders.yml @@ -0,0 +1 @@ +INHERIT: mkdocs.template.yml diff --git a/mkdocs.public.yml b/mkdocs.public.yml new file mode 100644 index 000000000..10afb876b --- /dev/null +++ b/mkdocs.public.yml @@ -0,0 +1,4 @@ +INHERIT: mkdocs.template.yml +# Omit the `typeset` plugin which is only available in the Insiders version. +plugins: + - search diff --git a/mkdocs.template.yml b/mkdocs.template.yml new file mode 100644 index 000000000..bfb74ec9d --- /dev/null +++ b/mkdocs.template.yml @@ -0,0 +1,105 @@ +site_name: uv +theme: + name: material + favicon: assets/favicon.ico + features: + - navigation.instant + - navigation.instant.prefetch + - navigation.instant.progress + - navigation.expand + - navigation.tracking + - content.code.annotate + - toc.integrate + - toc.follow + - navigation.path + - navigation.top + - content.code.copy + - content.tabs.link + palette: + # Note: Using the system theme works with the insiders version + # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: astral-light + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: astral-dark + toggle: + icon: material/brightness-4 + name: Switch to system preference + custom_dir: docs/.overrides +repo_url: https://github.com/astral-sh/uv +repo_name: uv +site_author: charliermarsh +site_url: https://docs.astral.sh/uv/ +site_dir: site/uv +markdown_extensions: + - admonition + - pymdownx.details + - toc: + permalink: "#" + - pymdownx.snippets: + - pymdownx.magiclink: + - attr_list: + - md_in_html: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite: + - pymdownx.superfences: + - markdown.extensions.attr_list: + - pymdownx.keys: + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.tabbed: + alternate_style: true +plugins: + - search + - typeset +extra_css: + - stylesheets/extra.css +extra: + analytics: + provider: fathom +nav: + - Introduction: index.md + - Getting started: + - Installation: installation.md + - First steps: first-steps.md + - Guides: + - Installing Python: guides/install-python.md + - Running scripts: guides/scripts.md + - Using tools: guides/tools.md + - Creating a project: guides/projects.md + - Concepts: + - Projects: preview/projects.md + - Command-line tools: preview/tools.md + - Python versions: python-versions.md + - Workspaces: preview/workspaces.md + - Dependency sources: preview/dependencies.md + - Resolution: resolution.md + - Caching: cache.md + - Authentication: configuration/authentication.md + - Configuration: + - Configuration files: configuration/files.md + - Environment variables: configuration/environment.md + - Integration guides: + - Using in Docker: guides/docker.md + - Using in GitHub Actions: guides/github.md + - Using in pre-commit: guides/pre-commit.md + - Low-level operations: + - Using environments: pip/environments.md + - Managing packages: pip/packages.md + - Inspecting packages: pip/inspection.md + - Declaring dependencies: pip/dependencies.md + - Locking environments: pip/compile.md + - Policies: + - Versioning: versioning.md + - Platform support: platforms.md + - Compatibility with pip: pip/compatibility.md