Skip to content

Simplify and update workspace environment docs. #2095

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Nov 9, 2025
Merged

Simplify and update workspace environment docs. #2095

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 0 additions & 123 deletions docs/how-to/environment/workspace.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,27 +103,6 @@ workspace.members = ["packages/*"]
workspace.parallel = true
```

## Cross-member dependencies

Workspace members can depend on each other. When installed, pip or uv will resolve the dependency relationships:

```toml tab="packages/app/pyproject.toml"
[project]
name = "app"
dependencies = ["core", "utils"]
```

```toml tab="pyproject.toml"
[tool.hatch.envs.default]
workspace.members = [
"packages/core",
"packages/utils",
"packages/app"
]
```

All workspace members are installed as editable packages. Pip or uv handles resolving the dependencies between app, core, and utils during installation.

## Monorepo example

Complete configuration for a typical monorepo structure:
Expand Down Expand Up @@ -198,105 +177,3 @@ workspace.members = [
]
scripts.test = "pytest plugins/{matrix:plugin}/tests {args}"
```

## Multi-service application example

Configuration for microservices development:

```toml config-example
[tool.hatch.envs.default]
workspace.members = ["shared"]
dependencies = ["pytest", "requests"]

[tool.hatch.envs.api]
workspace.members = [
"shared",
{path = "services/api", features = ["dev"]}
]
dependencies = ["fastapi", "uvicorn"]
scripts.dev = "uvicorn services.api.main:app --reload"

[tool.hatch.envs.worker]
workspace.members = [
"shared",
{path = "services/worker", features = ["dev"]}
]
dependencies = ["celery", "redis"]
scripts.dev = "celery -A services.worker.tasks worker --loglevel=info"

[tool.hatch.envs.integration]
workspace.members = [
"shared",
"services/api",
"services/worker",
"services/frontend"
]
dependencies = ["pytest", "httpx", "docker"]
scripts.test = "pytest tests/integration {args}"
```

## Documentation generation example

Configuration for generating documentation across packages:

```toml config-example
[tool.hatch.envs.docs]
workspace.members = [
{path = "packages/core", features = ["docs"]},
{path = "packages/cli", features = ["docs"]},
{path = "packages/plugins", features = ["docs"]}
]
dependencies = [
"mkdocs",
"mkdocs-material",
"mkdocstrings[python]"
]
scripts.serve = "mkdocs serve"
scripts.build = "mkdocs build"

[tool.hatch.envs.docs-api-only]
workspace.members = [
{path = "packages/core", features = ["docs"]}
]
template = "docs"
scripts.serve = "mkdocs serve --config-file mkdocs-api.yml"
```

## Development workflow example

Configuration supporting different development workflows:

```toml config-example
[tool.hatch.envs.dev]
workspace.members = ["packages/*"]
workspace.parallel = true
dependencies = [
"pytest",
"black",
"ruff",
"mypy",
"pre-commit"
]
scripts.setup = "pre-commit install"
scripts.test = "pytest {args}"
scripts.lint = ["ruff check .", "black --check .", "mypy ."]
scripts.fmt = ["ruff check --fix .", "black ."]

[tool.hatch.envs.feature]
template = "dev"
workspace.members = [
"packages/core",
"packages/{env:FEATURE_PACKAGE}"
]
scripts.test = "pytest packages/{env:FEATURE_PACKAGE}/tests {args}"

[[tool.hatch.envs.release.matrix]]
package = ["core", "utils", "cli"]

[tool.hatch.envs.release]
detached = true
workspace.members = ["packages/{matrix:package}"]
dependencies = ["build", "twine"]
scripts.build = "python -m build packages/{matrix:package}"
scripts.publish = "twine upload packages/{matrix:package}/dist/*"
```
Loading