From 82d613e23b0cfc8bf33ebec4b8e878b5cf8e3d48 Mon Sep 17 00:00:00 2001
From: emil <emil.simeonov@tutanota.com>
Date: Wed, 24 Jun 2026 22:48:06 +0000
Subject: [PATCH] DEVX-46: docs: add pyproject.toml dependency and pip.conf
 instructions for devx

---
 README.md     | 41 +++++++++++++++++++++++++++++++++++++----
 docs/index.md | 39 +++++++++++++++++++++++++++++++++++----
 2 files changed, 72 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 263882d..718cc0e 100644
--- a/README.md
+++ b/README.md
@@ -59,24 +59,57 @@ up by bumping their devx dependency.
 
 ## Installation
 
-Install from the Gitea PyPI registry:
+devx is published to the Gitea PyPI registry at
+`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
+The registry is publicly readable — no authentication required to install.
+
+### Quick install (one-off)
 
 ```bash
 pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```
 
-Or add the registry to your `pip.conf` / `pyproject.toml` and install normally:
+### Persistent configuration (recommended)
+
+Add the registry to `~/.pip/pip.conf` so `pip install devx` works without
+specifying `--index-url` every time:
+
+```ini
+[global]
+extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
+```
+
+### As a dependency in another project
+
+To use devx as a dependency in your `pyproject.toml`, add the registry as an
+extra index and list devx in your dependencies:
+
+```toml
+[project]
+dependencies = [
+    "devx>=0.11.1",
+]
+
+[tool.pip]
+extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
+```
+
+Then install normally:
 
 ```bash
-pip install devx
+pip install -e .
 ```
 
+> **Note:** If your project requires a specific devx version, pin it in
+> `dependencies` (e.g., `"devx==0.11.1"`) or use a version constraint
+> (e.g., `"devx>=0.11.1,<0.12"`).
+
 ### Optional extras
 
 devx ships optional dependency groups for different use cases:
 
 ```bash
-pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit)
+pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
 pip install "devx[molecule]"     # Molecule testing for Ansible projects
 pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
 ```
diff --git a/docs/index.md b/docs/index.md
index 17a43cb..698d5d0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -46,18 +46,49 @@ via environment variables and `pyproject.toml`, and inherit:
 
 ## Installation
 
-Install from the Gitea PyPI registry:
+devx is published to the Gitea PyPI registry at
+`https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple`.
+The registry is publicly readable — no authentication required to install.
+
+### Quick install (one-off)
 
 ```bash
 pip install devx --index-url https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
 ```
 
-Optional extras:
+### Persistent configuration (recommended)
+
+Add the registry to `~/.pip/pip.conf`:
+
+```ini
+[global]
+extra-index-url = https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple
+```
+
+Then `pip install devx` works without specifying `--index-url`.
+
+### As a dependency in another project
+
+Add devx to your `pyproject.toml` dependencies and configure the registry:
+
+```toml
+[project]
+dependencies = [
+    "devx>=0.11.1",
+]
+
+[tool.pip]
+extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
+```
+
+Pin a specific version if needed: `"devx==0.11.1"` or `"devx>=0.11.1,<0.12"`.
+
+### Optional extras
 
 ```bash
-pip install "devx[ci,lint]"      # CI runners and linting
+pip install "devx[ci,lint]"      # CI runners and linting (pytest, ruff, pyright, bandit, build, twine)
 pip install "devx[molecule]"     # Molecule testing for Ansible projects
-pip install "devx[dev]"          # Full local development
+pip install "devx[dev]"          # Full local development (ci + lint + build + twine)
 ```
 
 ## Architecture