-
-
+
+
@@ -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