From 73208479f6cf0f85cefd1899ad453b36ea64ba94 Mon Sep 17 00:00:00 2001 From: JRoot Junior Date: Fri, 2 Jan 2026 01:13:46 +0200 Subject: [PATCH] Expand contributing documentation with instructions for using `uv`, including dependency management, testing, linting, and docs workflows. --- docs/contributing.rst | 156 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index c68480b0..558601ab 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -88,6 +88,88 @@ Windows: It will install :code:`aiogram` in editable mode into your virtual environment and all dependencies. +Alternative: Using uv (Modern Approach) +---------------------------------------- + +As an alternative to the traditional :code:`pip` and :code:`venv` workflow, you can use `uv `_ - +a modern, fast Python package manager that handles virtual environments, dependency resolution, and package installation. + +**Benefits of using uv:** + +- 10-100x faster dependency resolution than pip +- Automatic virtual environment management +- Reproducible builds with lockfile +- Single tool for all package management needs + +**Installing uv:** + +Linux / macOS: + +.. code-block:: bash + + curl -LsSf https://astral.sh/uv/install.sh | sh + +Windows: + +.. code-block:: powershell + + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + +Or using pip: + +.. code-block:: bash + + pip install uv + +**Setup project with uv:** + +Instead of manually creating and activating a virtual environment, :code:`uv` handles this automatically: + +.. code-block:: bash + + # Clone the repository + git clone https://github.com/aiogram/aiogram.git + cd aiogram + + # Install all dependencies (creates .venv automatically) + uv sync --all-extras --group dev --group test + + # Install pre-commit hooks + uv run pre-commit install + +That's it! The :code:`uv sync` command creates a virtual environment in :code:`.venv/`, +installs all dependencies including optional extras and development tools, and generates +a :code:`uv.lock` file for reproducible builds. + +**Running commands with uv:** + +When using :code:`uv`, prefix commands with :code:`uv run` to execute them in the managed environment: + +.. code-block:: bash + + # Format code + uv run black aiogram tests examples + uv run isort aiogram tests examples + + # Run tests + uv run pytest tests + + # Run linting + uv run ruff check aiogram examples + uv run mypy aiogram + + # Start documentation server + uv run sphinx-autobuild --watch aiogram/ docs/ docs/_build/ + +Or use the Makefile commands which now support :code:`uv`: + +.. code-block:: bash + + make install # Uses uv sync + make lint # Uses uv run + make reformat # Uses uv run + make test # Uses uv run + Making changes in code ---------------------- @@ -101,38 +183,89 @@ Format the code (code-style) Note that this project is Black-formatted, so you should follow that code-style, too be sure You're correctly doing this let's reformat the code automatically: +Using traditional approach: + .. code-block:: bash black aiogram tests examples isort aiogram tests examples +Or with uv: + +.. code-block:: bash + + uv run black aiogram tests examples + uv run isort aiogram tests examples + +Or simply use Makefile: + +.. code-block:: bash + + make reformat + Run tests --------- All changes should be tested: +Using traditional approach: + .. code-block:: bash pytest tests +Or with uv: + +.. code-block:: bash + + uv run pytest tests + +Or use Makefile: + +.. code-block:: bash + + make test + Also if you are doing something with Redis-storage or/and MongoDB-storage, you will need to test everything works with Redis or/and MongoDB: +Using traditional approach: + .. code-block:: bash pytest --redis redis://:/ --mongo mongodb://:@: tests +Or with uv: + +.. code-block:: bash + + uv run pytest --redis redis://:/ --mongo mongodb://:@: tests + Docs ---- We are using `Sphinx` to render docs in different languages, all sources located in `docs` directory, you can change the sources and to test it you can start live-preview server and look what you are doing: +Using traditional approach: + .. code-block:: bash sphinx-autobuild --watch aiogram/ docs/ docs/_build/ +Or with uv: + +.. code-block:: bash + + uv run --extra docs sphinx-autobuild --watch aiogram/ docs/ docs/_build/ + +Or use Makefile: + +.. code-block:: bash + + make docs-serve + Docs translations ----------------- @@ -143,12 +276,27 @@ into different languages. Before start, let's up to date all texts: +Using traditional approach: + .. code-block:: bash cd docs make gettext sphinx-intl update -p _build/gettext -l +Or with uv: + +.. code-block:: bash + + uv run --extra docs bash -c 'cd docs && make gettext' + uv run --extra docs bash -c 'cd docs && sphinx-intl update -p _build/gettext -l ' + +Or use Makefile: + +.. code-block:: bash + + make docs-gettext + Change the :code:`` in example below to the target language code, after that you can modify texts inside :code:`docs/locale//LC_MESSAGES` as :code:`*.po` files by using any text-editor or specialized utilites for GNU Gettext, @@ -156,10 +304,18 @@ for example via `poedit `_. To view results: +Using traditional approach: + .. code-block:: bash sphinx-autobuild --watch aiogram/ docs/ docs/_build/ -D language= +Or with uv: + +.. code-block:: bash + + uv run --extra docs sphinx-autobuild --watch aiogram/ docs/ docs/_build/ -D language= + Describe changes ----------------