Skip to content

Commit df6e351

Browse files
committed
chore: add missing justfile recipes and standardization docs
- Add setup-completion recipe (bash tab completion for just) - Add docs-view recipe (open built docs in browser) - Add clean-build recipe (clean build artifacts) - Add verify-wheels alias (consistency with other repos) - Add publish meta-recipe (combines publish-pypi and publish-rtd) - Document justfile standardization in MODERNIZATION.md - Standard variables (PROJECT_DIR, UV_CACHE_DIR, VENV_DIR, ENVS) - Standard helpers (_get-spec, _get-system-venv-name, _get-venv-python) - Common Recipes Status matrix across all 6 WAMP repos - Manylinux wheel support documentation - Universe build recipe documentation Note: This work was completed with AI assistance (Claude Code).
1 parent a0f708f commit df6e351

2 files changed

Lines changed: 139 additions & 0 deletions

File tree

MODERNIZATION.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1407,6 +1407,82 @@ publish-rtd tag="":
14071407

14081408
**Blockers**: Requires Phase 1.2 complete (all sub-phases merged)
14091409

1410+
#### Phase 1.3 Justfile Standardization
1411+
1412+
As part of Phase 1.3, we audited and standardized justfiles across all 6 WAMP Python repos to ensure consistent developer experience.
1413+
1414+
##### Standard Variables (All 6 repos ✅)
1415+
1416+
| Variable | Description |
1417+
|----------|-------------|
1418+
| `PROJECT_DIR` | Project base directory (justfile_directory()) |
1419+
| `UV_CACHE_DIR` | uv cache directory (./.uv-cache) |
1420+
| `VENV_DIR` | Virtual environments directory (./.venvs) |
1421+
| `ENVS` | Supported Python environments (cpy314 cpy313 cpy312 cpy311 pypy311) |
1422+
1423+
##### Standard Helpers (All 6 repos ✅)
1424+
1425+
| Helper | Description |
1426+
|--------|-------------|
1427+
| `_get-spec` | Map Python version short name to full uv version spec |
1428+
| `_get-system-venv-name` | Get system-matching venv name (e.g., cpy311) |
1429+
| `_get-venv-python` | Get Python executable path for a venv |
1430+
1431+
##### Common Recipes Status
1432+
1433+
| Recipe | txaio | autobahn | zlmdb | cfxdb | wamp-xbr | crossbar |
1434+
|--------|-------|----------|-------|-------|----------|----------|
1435+
| `default` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1436+
| `setup-completion` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1437+
| `distclean` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1438+
| `list-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1439+
| `create` / `create-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1440+
| `install` / `install-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1441+
| `install-dev` / `install-dev-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1442+
| `install-dev-local` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1443+
| `install-tools` / `install-tools-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1444+
| `fix-format` / `check-format` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1445+
| `check-typing` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1446+
| `test` / `test-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1447+
| `docs` / `docs-clean` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1448+
| `docs-view` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1449+
| `build` / `build-all` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1450+
| `build-sourcedist` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1451+
| `clean-build` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1452+
| `verify-wheels` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1453+
| `publish` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1454+
| `publish-pypi` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1455+
| `publish-rtd` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
1456+
1457+
##### Manylinux Wheel Support
1458+
1459+
For repos with native extensions (zlmdb, autobahn-python), the `build` recipe now includes auditwheel repair to produce manylinux-compatible wheels matching GitHub CI output:
1460+
1461+
```bash
1462+
# Convert linux wheels to manylinux format using auditwheel
1463+
if [ -x "${VENV_PATH}/bin/auditwheel" ]; then
1464+
for wheel in dist/*-linux_*.whl; do
1465+
if [ -f "$wheel" ]; then
1466+
"${VENV_PATH}/bin/auditwheel" repair "$wheel" -w dist/
1467+
rm "$wheel" # Remove original linux wheel
1468+
fi
1469+
done
1470+
fi
1471+
```
1472+
1473+
##### Universe Build Recipe
1474+
1475+
The crossbar repo has a `build-universe` recipe that builds all 6 WAMP repos in dependency order:
1476+
1477+
1. txaio
1478+
2. autobahn-python
1479+
3. zlmdb
1480+
4. cfxdb
1481+
5. wamp-xbr
1482+
6. crossbar
1483+
1484+
This produces wheels and source distributions in `dist-universe/` matching GitHub CI artifacts.
1485+
14101486
## Phase 2: Integration Test Coverage
14111487

14121488
**Objective**: End-to-end integration testing across the entire WAMP stack.

justfile

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,41 @@ _get-venv-python venv="":
102102
# -- General/global helper recipes
103103
# -----------------------------------------------------------------------------
104104

105+
# Setup bash tab completion for the current user (to activate: `source ~/.config/bash_completion`).
106+
setup-completion:
107+
#!/usr/bin/env bash
108+
set -e
109+
110+
COMPLETION_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/bash_completion"
111+
MARKER="# --- Just completion ---"
112+
113+
echo "==> Setting up bash tab completion for 'just'..."
114+
115+
# Check if we have already configured it.
116+
if [ -f "${COMPLETION_FILE}" ] && grep -q "${MARKER}" "${COMPLETION_FILE}"; then
117+
echo "--> 'just' completion is already configured."
118+
exit 0
119+
fi
120+
121+
echo "--> Configuration not found. Adding it now..."
122+
123+
# 1. Ensure the directory exists.
124+
mkdir -p "$(dirname "${COMPLETION_FILE}")"
125+
126+
# 2. Add our marker comment to the file.
127+
echo "" >> "${COMPLETION_FILE}"
128+
echo "${MARKER}" >> "${COMPLETION_FILE}"
129+
130+
# 3. CRITICAL: Run `just` and append its raw output directly to the file.
131+
# No `echo`, no `eval`, no quoting hell. Just run and redirect.
132+
just --completions bash >> "${COMPLETION_FILE}"
133+
134+
echo "--> Successfully added completion logic to ${COMPLETION_FILE}."
135+
136+
echo ""
137+
echo "==> Setup complete. Please restart your shell or run the following command:"
138+
echo " source \"${COMPLETION_FILE}\""
139+
105140
# Remove ALL generated files, including venvs, caches, and build artifacts. WARNING: This is a destructive operation.
106141
distclean:
107142
#!/usr/bin/env bash
@@ -666,6 +701,20 @@ docs-check venv="": (install-tools venv)
666701
echo "==> Checking documentation build..."
667702
"${VENV_PATH}/bin/sphinx-build" -nWT -b dummy docs/ docs/_build
668703
704+
# Open the built documentation in the default browser
705+
docs-view venv="": (docs venv)
706+
#!/usr/bin/env bash
707+
set -e
708+
echo "==> Opening documentation in viewer..."
709+
if command -v xdg-open &> /dev/null; then
710+
xdg-open docs/_build/html/index.html
711+
elif command -v open &> /dev/null; then
712+
open docs/_build/html/index.html
713+
else
714+
echo "==> Could not detect browser opener. Please open manually:"
715+
echo " docs/_build/html/index.html"
716+
fi
717+
669718
# Clean the generated documentation
670719
docs-clean:
671720
echo "==> Cleaning documentation build artifacts..."
@@ -675,6 +724,14 @@ docs-clean:
675724
# -- Building and Publishing
676725
# -----------------------------------------------------------------------------
677726

727+
# Clean build artifacts
728+
clean-build:
729+
#!/usr/bin/env bash
730+
echo "==> Cleaning build artifacts..."
731+
rm -rf build/ dist/ *.egg-info/
732+
find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
733+
echo "==> Build artifacts cleaned."
734+
678735
# Build wheel only (usage: `just build cpy312`)
679736
build venv="": (install-build-tools venv)
680737
#!/usr/bin/env bash
@@ -856,6 +913,9 @@ build-verifydist venv="": (install-build-tools venv)
856913
# Legacy alias for build-verifydist
857914
verify-dist venv="": (build-verifydist venv)
858915

916+
# Alias for consistency with other WAMP repos
917+
verify-wheels venv="": (build-verifydist venv)
918+
859919
# Path to parent directory containing all WAMP Python repos
860920
WAMP_REPOS_DIR := parent_directory(justfile_directory())
861921

@@ -1967,3 +2027,6 @@ publish-rtd tag="":
19672027
echo " 2. Click 'Build a version'"
19682028
echo " 3. Select the tag: ${TAG}"
19692029
echo ""
2030+
2031+
# Publish package to PyPI and trigger RTD build (meta-recipe)
2032+
publish venv="" tag="": (publish-pypi venv tag) (publish-rtd tag)

0 commit comments

Comments
 (0)