Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation feedback #5605

Open
zanieb opened this issue Jul 30, 2024 · 95 comments
Open

Documentation feedback #5605

zanieb opened this issue Jul 30, 2024 · 95 comments
Assignees
Labels
documentation Improvements or additions to documentation tracking A "meta" issue that tracks completion of a bigger task via a list of smaller scoped issues.

Comments

@zanieb
Copy link
Member

zanieb commented Jul 30, 2024

This is a tracking issue for feedback on the new documentation at https://docs.astral.sh/uv/

@zanieb zanieb added the tracking A "meta" issue that tracks completion of a bigger task via a list of smaller scoped issues. label Jul 30, 2024
@zanieb zanieb self-assigned this Jul 30, 2024
@zanieb zanieb added the documentation Improvements or additions to documentation label Jul 30, 2024
@dmfigol
Copy link

dmfigol commented Aug 16, 2024

https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences
it is not clear with what subcommand i can use --python-preference only-managed to set it permanently.

@zanieb
Copy link
Member Author

zanieb commented Aug 16, 2024

We don't have a commands to modify a persistent configuration file — you can put it in a uv.toml or pyproject.toml per

Thanks for the feedback though! Sounds like we should link to the persistent configuration documentation here.

@zanieb zanieb pinned this issue Aug 20, 2024
@shoucandanghehe
Copy link

A little suggestion: add the use of generate-shell-completion to First steps with uv

I habitually use --help to see what commands I can use.
Then I realized that there was no completion command, and didn't search for it until I want to open an issue!😝

PS: I don't understand why it should be hidden in --help. Except for this command, the outputs of help and --help are almost identical!

@zanieb
Copy link
Member Author

zanieb commented Aug 21, 2024

I'm not sure why it's hidden — I copied this from Ruff. I think it might be because it shifts the indent for the rest of the commands way to the right and dramatically reduces the space we have for concise documentation.

Thanks for the feedback! Tracked in #6153

@zanieb
Copy link
Member Author

zanieb commented Aug 21, 2024

Maybe we can improve the uvx to uv tool transition in the guide #6334 (comment)

@gusutabopb
Copy link

gusutabopb commented Aug 22, 2024

On getting-started/installation/#standalone-installer it says

When uv is installed via the standalone installer, self-updates are enabled

This sounded to me as if uv would automatically update itself (like many GUI apps do), but it seems this is not the case. I guess it just means uv self update is not available at all unless the standalone installer was used. I think wording here could be improved to clarify that.

By the way, I added this to my crontab to get auto-updates:

00 00 * * * uv self update

@minusf
Copy link

minusf commented Aug 22, 2024

Minor confusion for me in https://docs.astral.sh/uv/concepts/tools/, emphasis mine:

Tools can also be installed with uv tool install, in which case their executables are available on the PATH — an isolated virtual environment is still used but it is not treated as disposable.

...

When running a tool with uvx or uv tool run, a virtual environment is stored in the uv cache directory and is treated as disposable.

For uv tool, the venv is, or is not treated as disposable?

Furthermore, what does it mean "disposable" in this context?

In my first reading I understood uvx only as a convenience alias to uv tool run. However they seem to create different types of venvs in different locations in different ways and I am not able to understand the difference after reading this concept page...

If I do uvx posting and uv tool install posting && uv tool run posting, what is the conceptual difference and which one should i use?

@prrao87
Copy link

prrao87 commented Aug 22, 2024

Maybe we can improve the uvx to uv tool transition in the guide #6334 (comment)

One suggestion would be to reiterate in the CLI reference docs for uv tool run that it's also available as uvx. Users might end up there via google searches and not be aware that there's an alias.

Another thing is that in the tool concepts page, it directly references uvx in these ways:

Tools can be invoked without installation using uvx ...
When running a tool with uvx or uv tool run, a virtual environment is stored...

In both these cases, the implicit assumption is that the user knows that uvx is an alias for only uv tool run and that it invokes the tool instead of installing it (hence the x, rather than r, which is what one would intuitively think would be the alias). But the only way to know these distinctions is to have carefully read the tools guide section of the docs first, and not all users may end up on the guide page first and read things in the exact order they're shown in the sidebar 😅.

@zanieb
Copy link
Member Author

zanieb commented Aug 22, 2024

(Thanks for the feedback everyone, I'll attempt to address all that)

We should talk about defining constraints in the pyproject.toml in the project concept per #6425

@zanieb
Copy link
Member Author

zanieb commented Aug 22, 2024

@gusutabopb let me know if #6468 is sufficient!

@minusf and @prrao87 I've attempted to address those in:

@alandelevieTR
Copy link

Hi! I hope this is the correct place, but I would request examples for:

Other indexes[#](https://docs.astral.sh/uv/#other-indexes)

uv is also known to work with JFrog's Artifactory, the Google Cloud Artifact Registry, and AWS Code Artifact.

I ask because this does not work from my existing pyproject.toml:

my-custom-package = {version = "0.0.5", source = "my-pip-repo-happens-to-be-gcp-artifact-registry"}
# ...

[[tool.poetry.source]]
name = "my-pip-repo-happens-to-be-gcp-artifact-registry"
url = "https://us-west2-python.pkg.dev/my-gcp-org/hello/simple/"
priority = "explicit"

I add auth to the config by running:

$ pip install keyring
$ pip install keyrings.google-artifactregistry-auth
$ gcloud auth application-default login
$ poetry config http-basic.my-pip-repo-happens-to-be-gcp-artifact-registry oauth2accesstoken "$(gcloud auth print-access-token)"

Finding the equivalent of that last line for uv is what has me stumped.

I'm similarly interested in jfrog examples, but this is the one I can provide the most specific details on.

@gusutabopb
Copy link

The FastAPI guide needs to be updated to reflect the changes introduced to the default behavior of uv init in version 0.4.0. The current docs still say a src -based layout would be created: https://docs.astral.sh/uv/guides/integration/fastapi/#initializing-a-fastapi-project

@devmcp
Copy link

devmcp commented Sep 5, 2024

uv can be installed on Windows using winget, but this isn't mentioned in the docs. Could/should it be added as an alternative installation method along with homebrew etc?

@alper
Copy link

alper commented Sep 10, 2024

I'm not sure why there's a python-version file if this information is also in the pyproject.toml.

@shunichironomura
Copy link

The documentation about running scripts using the inline metadata (link) doesn't mention support for specifying the dependency sources via the tool.uv.sources section, but it does seem to support it when I run, for example:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# [tool.uv.sources]
# requests = { git = "https://github.com/psf/requests.git", tag = "v2.32.2" }
# ///

import requests

print(requests.__version__) # 2.32.2 (2.32.3 is the latest)

I think the documentation can be explicit about officially supporting (or not supporting) it.

@zanieb
Copy link
Member Author

zanieb commented Sep 19, 2024

@shunichironomura thanks! I think we need to create a separate "Scripts" concept page because that's way too advanced for the "guide" documentation.

@scimas
Copy link

scimas commented Sep 23, 2024

Would be nice to have information on whether virtual workspaces (no project and build-system sections in pyproject.toml?) like Cargo are supported.

@charliermarsh
Copy link
Member

You might be looking for this: https://docs.astral.sh/uv/concepts/projects/#applications

@scimas
Copy link

scimas commented Sep 23, 2024

That is still an application that has its own python code from what I can tell. The Cargo virtual workspaces just combine related packages together, where there isn't necessarily one "main" binary.

Taking from the workspace example in uv docs,

albatross
├── packages
│   ├── bird-feeder
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── bird_feeder
│   │           ├── __init__.py
│   │           └── foo.py
│   ├──squirrel-feeder
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── squirrel_feeder
│   │           ├── __init__.py
│   │           └── foo.py
│   └── seeds
│       ├── pyproject.toml
│       └── src
│           └── seeds
│               ├── __init__.py
│               └── bar.py
├── pyproject.toml
├── README.md
└── uv.lock

imagine bird-feeder and squirrel-feeder were equally important packages with the common seeds dependency.

And just to be clear, I'm not asking this feature to be implemented, only clarification on whether or not it is supported because the documentation page explicitly refers to Cargo.

@willmurphyscode
Copy link

I have a couple questions about the lockfile after reading the docs on it.

Is the uv.lock file specified anywhere? I looked at https://docs.astral.sh/uv/concepts/projects/#project-lockfile and expected to find a schema or a link to a schema or specification for what can go in uv.lock.

The reason I'm looking for a schema / specification is that I would like to be able to parse uv.lock files so that I can add a uv.lock parser Syft.

My other question is whether you expect the uv.lock file to remain stable, or whether there is planned work to change or extend its schema.

@astrojuanlu
Copy link

The Cargo virtual workspaces just combine related packages together, where there isn't necessarily one "main" binary.

@scimas Virtual projects were removed in #6720 (from the docs at least - cannot quickly find other pointers)

@charliermarsh
Copy link
Member

@scimas -- Yeah that layout is fully supported. You can create a pyproject.toml at the root that is not itself linked to any Python code, and just lists workspace members and dependencies, i.e., a virtual workspace root as in Cargo.

@astrojuanlu -- We removed most mentions of "virtual" since it wasn't a familiar concept, but the idea of a project that just lists members and dependencies is still supported.

@abitrolly
Copy link

@eliasdabbas I like the Python version of the link checker. Definitely useful. Would be interested to see how it compares to Rust based https://lychee.cli.rs/

@eliasdabbas
Copy link

@abitrolly I'm not familiar with Lychee, but I just took a look. Based on what I saw so far:

Pros: It can check links in a tree locally, supports .md .rst and HTML. This makes it great for pre-commit checks/hooks.

Cons: It doesn't support recursive crawling of websites, which includes discovering links, following them, redirects, etc.

Python pros: Supports recursive crawling with customizable rules, and can be as fast as you want it to be.

Python cons: Does not support .md or .rst.

So if you want the actual live website the advertools/Python solution seems better, if you want to check .md or .rst files, it seems Lychee is the good choice. Again I'm not that familiar with it, so take what I said with a grain of salt.

@carrollpaul
Copy link

When I build and run the container from the Docker example as-is, I get this error:

Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create fa
iled: runc create failed: unable to start container process: exec: "fastapi": executable file not found in $PATH: 
unknown

@zanieb
Copy link
Member Author

zanieb commented Jan 14, 2025

@carrollpaul I tested that just now and cannot reproduce. Please open an issue with a reproduction.

@clbarnes
Copy link

The docs for deploying a zip archive for AWS lambda ( https://docs.astral.sh/uv/guides/integration/aws-lambda/#deploying-a-zip-archive ) includes the usage of uv pip install's --no-installer-metadata argument; that doesn't seem to exist https://docs.astral.sh/uv/reference/cli/#uv-pip-install

@charliermarsh
Copy link
Member

It exists, it's just not visible on the CLI. It's analogous to: https://docs.astral.sh/uv/configuration/environment/#uv_no_installer_metadata.

@judgewooden
Copy link

I have switched to uv for most of my projects and am wondering if there is an easy way to create a snapshot of the environment. I need to experiment with upgrades and dependencies, and if things go wrong, revert to the original snapshot.

In the past, I used pip freeze > requirements-pre-upgrade.txt before making changes. I know I can do the same with uv pip freeze, but I was curious if there is a better way to handle this using uv tools.

@debnath-d
Copy link

I need to experiment with upgrades and dependencies, and if things go wrong, revert to the original snapshot.

In the past, I used pip freeze > requirements-pre-upgrade.txt before making changes. I know I can do the same with uv pip freeze, but I was curious if there is a better way to handle this using uv tools.

@judgewooden

All information is contained in pyproject.toml and uv.lock. Just backup these two files.

If things go wrong, replace these files with the backed up files and run uv sync.

@edmorley
Copy link
Contributor

edmorley commented Jan 26, 2025

Some misc docs feedback before I forget...

Locking and syncing concepts page

If I search the docs for "sync", the top result is the "Locking and Syncing" concepts page:
https://docs.astral.sh/uv/concepts/projects/sync/

The page has "syncing" in the title and "sync" in the URL, but the page content itself really only seems to be about locking rather than syncing, which was surprising - since I was hoping to find more about uv sync?

uv sync CLI reference docs hidden in search results

After not finding what I was after on the "Locking and Syncing" concepts page, I tried searching for "sync" again, hoping to find the uv sync CLI reference docs (ie: https://docs.astral.sh/uv/reference/cli/#uv-sync).

However, instead the search results preview highlights some of the uv pip usage docs instead (with the uv sync content being hidden under the "9 more on this page" collapsed section).

eg:

Image

I'm presuming this is mostly due to the way mkdocs/its search plugin is designed, so I don't know if there is much that can be done (other than eg splitting CLI command pages up into smaller chunks?), and now I know to check the collapsed sections I can work around it - but I imagine this may hinder docs discovery for others too?

Clarifying the difference between python-downloads and python-preference

As part of deciding which uv sync arguments I should use in our build scripts, I read through the CLI command reference docs here:
https://docs.astral.sh/uv/reference/cli/#uv-sync

I knew I wanted to ensure uv always used our own Python distribution, rather than downloading a uv-managed installation - however, at first glance it wasn't immediately apparent whether I should be using python-downloads, python-preference, or both. (ie: Part of that uncertainty was wondering whether one option was a superset of the other, or if they were orthogonal.)

I was able to work it out after using doc search to find other pages like these:
https://docs.astral.sh/uv/concepts/python-versions/#disabling-automatic-python-downloads
https://docs.astral.sh/uv/concepts/python-versions/#adjusting-python-version-preferences

...but I wonder if the following might help:
(a) some backlinks from the reference pages back to the concepts sections (both the CLI reference usage docs, and the settings reference docs)
(b) A half-sentence or so added to both sections on the concept page explaining how they interact

Understanding what uv sync installs by default

When reading https://docs.astral.sh/uv/reference/cli/#uv-sync it wasn't immediately clear to me what dependency groups if any would be installed by default.

For example, the intro for the uv sync command doesn't mention what it installs, and none of the CLI args like --all-groups and related hint at it. From seeing the --no-dev arg I was able to infer that dev dependencies might be installed by default, but I had to search the docs manually to find:
https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies
https://docs.astral.sh/uv/concepts/projects/dependencies/#default-groups

I think some backlinks from the CLI args to the concepts docs would similarly help in this case.

General docs discoverability/navigation/ordering

I think several of the issues above only occurred because:

  1. I had skipped over some of the concept docs and used the CLI command reference docs as my starting point.
  2. The CLI reference docs don't tend to backlink to the other parts of the docs.

I'm normally someone that fully reads docs from the start/intro - I think part of the reason I skipped ahead was due to the volume of the docs (eg number of sections listed in the sidebar), and some of the earlier docs sections being less relevant to me (eg running scripts, manually managing Python installations, installing/running tools).

I don't think the volume of docs can really be avoided (uv does a lot, and comprehensive docs are needed/worthwhile), but I wonder if some re-ordering or adjusting of the initial intro/sections might help? For example, to me uv sync is uv's bread and butter use-case, but yet it's mentioned quite late in the intro (I think this might have been part of the person's issue in #10813 too?).

I also think the size of the docs means that backlinks from one-section to another (particularly CLI reference -> concepts) are particularly important for ensuring people end up in the right place if their initial entry-point to the docs wasn't ideal (eg an experienced user who jumps ahead to the CLI reference section, or if a search engine deep links to a reference page etc).

Anyway, thank you for having put so much time into docs already - hope the above was helpful (I know it's hard to get fresh eyes back on content with which you're already familiar).

@debnath-d
Copy link

debnath-d commented Feb 1, 2025

Perhaps it would be a good idea to point this out: https://docs.astral.sh/uv/reference/settings/#find-links on this page: https://docs.astral.sh/uv/configuration/indexes ?

@zanieb

@charliermarsh
Copy link
Member

That’s awesome feedback, thanks @edmorley.

@cmsirbu
Copy link

cmsirbu commented Feb 7, 2025

I'm having some difficulty with the Build Systems as a new uv user converting a project from poetry. So Poetry has its own build backend, which means I've never had to choose and this is where I think the docs could be more helpful.

Right now, the docs are explaining what a build system does for you and mentions that you can choose one with a parameter to uv init, but otherwise sends you to undefined external docs for your chosen build system (works only if you know what to choose in the first place). Some questions arise here:

  • What should I choose? If there's an opinionated default, docs should guide me towards setting it up correctly.
  • Do I need to install it alongside uv or does it manage that for me?
  • What happens if I don't define it or have an incompatible build-backend defined (e.g. migrating from Poetry).

And because I'm still in poetry/uv limbo, I have this still defined, but uv build seems to work fine despite not explicitly supporting Poetry as a backend. Not trying to turn this into a migration guide, but just to reinforce the questions above.

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"
> uv build
Building source distribution...
Building wheel from source distribution...
Successfully built dist/mkdocs_ansible_collection-0.2.1.tar.gz
Successfully built dist/mkdocs_ansible_collection-0.2.1-py3-none-any.whl

@zanieb
Copy link
Member Author

zanieb commented Feb 7, 2025

uv supports all build backends because we are a standards-complaint build frontend. The uv init command only supports a subset of build backends, because those are the ones that have received a pull request adding the necessary template.

We don't have an opinionated default. We use hatchling right now, because we think it's a reasonable option. We're working on our own build backend, which will be used by default eventually. uv init --package or uv init --lib will set up the "default" build backend for you.

If you don't define a build backend, we won't install your project itself into the environment (but will still install its dependencies).

I believe these things are outlined in https://docs.astral.sh/uv/concepts/projects/init/#creating-projects (in addition to the build system document you referenced).

We could clarify the role of build frontends in the document you linked though.

@rsyring
Copy link

rsyring commented Feb 21, 2025

I'm normally someone that fully reads docs from the start/intro - I think part of the reason I skipped ahead was due to the volume of the docs (eg number of sections listed in the sidebar),

I think digestibility of the sidebar could be made better with some styling changes. Currently, there isn't enough contrast between headings in the nav and the nav items. They are almost the same size, use the same font, have the same spacing, same color, etc. To me at least, that makes them run together and feels a bit overwhelming. Makes it harder to visually scan for what I'm looking for.

Consider mise's docs which have a similar volume of content in the sidebar nav but, at least to me, don't feel nearly as "crowded" or overwhelming:

Image

@sanmai-NL
Copy link

The section Resolution - Required environments doesn't explain the syntax and certainly not the semantics of this environment marker language. From uv's docs on functionally similar features, I found a reference to PEP 508. That, however, is marked as deprecated when visited, and superseded by Dependency specifiers.

I propose that uv's documents this language in a single place, that references Dependency specifiers and just that.

@zanieb
Copy link
Member Author

zanieb commented Feb 24, 2025

I think digestibility of the sidebar could be made better with some styling changes. Currently, there isn't enough contrast between headings in the nav and the nav items

Yeah I agree. This has been hard to get right and I've spent way too many hours futzing with it.

Unfortunately just copying over the colors from mise isn't great, imo

Image Image Image

@zanieb
Copy link
Member Author

zanieb commented Feb 24, 2025

Similarly, I think the bold looks bad

Image

@cmsirbu
Copy link

cmsirbu commented Feb 24, 2025

How about this (fully realizing it steals the active link colour).

Image

Image

  • Remove the padding override for inner menu items (leave it at the theme default?)
  • Make categories more emphasized using md-nav__link--active

@rsyring
Copy link

rsyring commented Feb 24, 2025

@cmsirbu - I'm terrible at design. I usually try to find a template that has this done "right" by someone who knows aesthetics better than me. :) But, here are some thoughts:

  • I think the latest attempt is an improvement worth publishing.
  • What's the third level nav look like. I.e. when you are in "Integrations >" or "Projects >"?
  • Try: making the 2nd level nav one size smaller font?
  • I'm not a fan of the "purple" color in the light background version. There isn't enough contrast between that and white IMO. But that might be a different issue for a different time.

HTH. :)

@zanieb
Copy link
Member Author

zanieb commented Feb 24, 2025

I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.

@zanieb
Copy link
Member Author

zanieb commented Feb 24, 2025

It's also worth noting that ~half of the Mise nav is below the page fold. It's an explicit goal to minimize that here.

I think the proper fix for this is probably to add horizontal sections, which I've explored but will requires some serious reorganization and isn't a priority at the moment.

@cmsirbu
Copy link

cmsirbu commented Feb 24, 2025

@rsyring There's a limit to what one can do in a browser "inspect" window with average css skills, I know when to stop 🙂

I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.

It's more of a take from it what might be useful than "do this".

More to the point, I initially only wanted to post the padding option, which might be a good solution for adding visual separation if you don't want to increase the vertical spacing too much (to keep as much as possible on the screen).

Is it too much indentation? 🤷🏻 It's python we're talking about...

Image

@rsyring
Copy link

rsyring commented Feb 24, 2025

It's also worth noting that ~half of the Mise nav is below the page fold. It's an explicit goal to minimize that here.

I'm not sure concern about what's above the fold is that helpful in technical documentation, especially navigation when it's intuitive, especially for technical users, to want to scan through something to easily get the "lay of the land." That's usually reserved for a different type of content and user interaction.

The audience who reads these docs is technical and giving them the ability to easily scan what the docs offer is a more important concern. I've never felt any hesitation when reviewing mise's docs b/c there is a lot of navigation. On the contrary, I've always found it helpful b/c it makes me aware of what's the there but easily allows me to move past it when I'm focused on a specific task.

To move this out of the realm of opinion, this might be a helpful reference: https://www.nngroup.com/articles/eyetracking-tasks-efficient-scanning/#toc-design-for-efficient-scanning-7

I think the proper fix for this is probably to add horizontal sections, which I've explored but will requires some serious reorganization and isn't a priority at the moment.

I'd encourage you to avoid horizontal navigation b/c it takes the scanning from a single dimension (vertical) to two dimensions (vertical + horizontal) and perhaps three dimensions if you have to click into a page in a section before you see it's horizontal navigation change. Makes getting the lay of the land much more difficult.

I think your current nav, two layers on left plus page TOC on the right once you are on a page is one of the best docs layout there is. Just need to visually de-clutter the left nav.

I guess I don't really see that as a clear step forward, especially since it clobbers the active link styling.

IMO, it is a clear step forward. Maybe not the last step, but the change in indentation and padding is a significant improvement.

I guess I'd have to see the full results but I didn't see anything that required clobbering the active link styling in the screenshots @cmsirbu provided. (missed a comment regarding)

Is it too much indentation? 🤷🏻 It's python we're talking about...

Nope. Just right IMO.

Don't forgot to preview the mobile/responsive versions.

Are all the font sizes the same? I think a slightly smaller font at each level will enhance visual distinction.

@rsyring
Copy link

rsyring commented Feb 24, 2025

Should we move the specifics of the nav changes to a different issue to avoid overwhelming this one?

@zanieb
Copy link
Member Author

zanieb commented Feb 24, 2025

Let's chat in #11757

@jromal

This comment has been minimized.

@Nugine
Copy link

Nugine commented Mar 10, 2025

(uv 0.6.5)
uv pip install does not update pyproject.toml or uv.lock. It seems surprising for new users.

@zanieb
Copy link
Member Author

zanieb commented Mar 10, 2025

(uv 0.6.5) uv pip install does not update pyproject.toml or uv.lock. It seems surprising for new users.

pip does not do this, nor will uv pip. I think the solution here is #5200

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation tracking A "meta" issue that tracks completion of a bigger task via a list of smaller scoped issues.
Projects
No open projects
Status: No status
Development

No branches or pull requests