Simplify instructions for installing dependencies with uv

[browniebroke]

Since the instructions were added in #11322, uv gained a new capability to run uv sync and uv run enabling some simplifications

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--11655.org.readthedocs.build/en/11655/

• Developer's documentation (dev): https://dev--11655.org.readthedocs.build/en/11655/

[humitos]

Isn't it required the -m here?

[browniebroke]

uv run mkdocs tries to run the mkdocs binary, while uv run -m mkdocs tries to run mkdocs as module, and AFAIK both work:

 ➜ uv run -m mkdocs --help
Usage: python -m mkdocs [OPTIONS] COMMAND [ARGS]...

  MkDocs - Project documentation with Markdown.

Options:
  -V, --version         Show the version and exit.
  -q, --quiet           Silence warnings
  -v, --verbose         Enable verbose output
  --color / --no-color  Force enable or disable color and wrapping for the output. Default is auto-detect.
  -h, --help            Show this message and exit.

Commands:
  build      Build the MkDocs documentation.
  get-deps   Show required PyPI packages inferred from plugins in mkdocs.yml.
  gh-deploy  Deploy your documentation to GitHub Pages.
  new        Create a new MkDocs project.
  serve      Run the builtin development server.

 ➜ uv run mkdocs --help 
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...

  MkDocs - Project documentation with Markdown.

Options:
  -V, --version         Show the version and exit.
  -q, --quiet           Silence warnings
  -v, --verbose         Enable verbose output
  --color / --no-color  Force enable or disable color and wrapping for the output. Default is auto-detect.
  -h, --help            Show this message and exit.

Commands:
  build      Build the MkDocs documentation.
  get-deps   Show required PyPI packages inferred from plugins in mkdocs.yml.
  gh-deploy  Deploy your documentation to GitHub Pages.
  new        Create a new MkDocs project.
  serve      Run the builtin development server.

[humitos]

Thanks! I don't have too much experience with uv, but I'm happy to merge this if you already tested it on Read the Docs. Do you have a working example?

[browniebroke]

Great question 😄 Yes, we use this in cookiecutter-django: cookiecutter/cookiecutter-django#5440

[Zethson]

I get

Using CPython 3.11.9 interpreter at: /home/docs/.asdf/installs/python/3.11.9/bin/python
Creating virtual environment at: .venv
error: Unable to find lockfile at `uv.lock`. To create a lockfile, run `uv lock` or `uv sync`.

for

uv sync --extra docs --frozen

I assume this requires a lock file?

[browniebroke]

I assume this requires a lock file?

Yes, of course

[Zethson]

The old instructions don't so I consider this a regression. Not every project (I'd argue very few at the moment) are using uv lockfiles.

[browniebroke]

As far as I understand, the uv venv... and uv pip install... were compatibility commands too meet users where they are with bare virtaulenv and pip usages. The modern way is to use the first party commands uv sync, uv run and yes, lockfiles.

I didn't know it was possible to opt-out of lockfile with uv... If you don't want lockfiles, what's the point of uv?

The old instructions don't so I consider this a regression

That's only a documented recommended way, you have to copy the config into your own project. Then you're free to branch it and adapt it however you like, calling that a "regression" a bit of a strong wording IMO 😄 Perhaps add a note after the snippet that this workflow needs a lockfile?