Development¶

This guide covers the day-to-day workflow for improving recipes, examples, and docs in this repository.

Local setup¶

git clone https://github.com/yeongseon/azure-functions-python-cookbook.git
cd azure-functions-python-cookbook
python -m venv .venv
source .venv/bin/activate
make install

If you do not use Make:

pip install -e ".[dev,docs]"

Development workflow¶

Pick a recipe-driven change.
Update the recipe narrative in recipes/.
Update matching runnable example in examples/.
Update docs in docs/ (overview pages and recipe pages).
Run checks and docs build.

Tip

Keep recipe text and runnable example behavior synchronized. Reviewers should be able to follow docs and reproduce behavior.

Useful make targets¶

Command	Purpose
`make format`	Format code
`make lint`	Ruff + mypy checks
`make test`	Run test suite
`make security`	Run Bandit security checks
`make check-all`	Lint + type + test + security
`make docs`	Build MkDocs site
`make docs-serve`	Serve docs locally

Running examples during development¶

HTTP API Basic¶

cd examples/http_api_basic
pip install -r requirements.txt
func start

HTTP API with OpenAPI¶

cd examples/http_api_openapi
pip install -r requirements.txt
func start

Visit http://localhost:7071/api/docs for Swagger UI.

GitHub Webhook¶

cd examples/github_webhook
pip install -r requirements.txt
func start

Set GITHUB_WEBHOOK_SECRET before testing signed requests.

Queue Worker¶

cd examples/queue_worker
pip install -r requirements.txt
func start

Use Azurite for local queue execution.

Timer Job¶

cd examples/timer_job
pip install -r requirements.txt
func start

Quality bar for pull requests¶

Clear mapping between recipe and example
Accurate local run instructions
Explicit failure handling in code examples
Production considerations documented
All checks passing (make check-all, make docs)

Documentation-specific workflow¶

When editing docs:

Keep section structure consistent across recipe pages.
Use code fences (bash, python, json, text) explicitly.
Add cross-links to related recipes.
Add admonitions for warnings and tips where useful.
Confirm links and file paths still match repository layout.

Before opening a PR¶

make check-all
make docs

Then verify:

New recipe pages are linked in mkdocs.yml
Example paths referenced in docs are correct
No secrets or local-only files are committed