diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..37c68b73 --- /dev/null +++ b/Makefile @@ -0,0 +1,83 @@ +.PHONY: help dev-install install-python pre-commit setup-env setup test lint docs clean tox run-tests + +help: + @echo "AIT-Core Development Makefile" + @echo "=============================" + @echo "" + @echo "Available targets:" + @echo " setup-env - Create and activate poetry virtual environment" + @echo " dev-install - Install package with development dependencies" + @echo " install-python - Install all required Python versions via pyenv" + @echo " pre-commit - Install pre-commit and pre-push hooks" + @echo " setup - Run full development setup (setup-env + dev-install + pre-commit + install-python)" + @echo " test - Run test suite with pytest" + @echo " tox - Run full tox build (tests, docs, linting)" + @echo " lint - Run linting pipeline" + @echo " docs - Build documentation" + @echo " clean - Remove build artifacts" + @echo "" + @echo "Before running 'make setup', ensure you have:" + @echo " - poetry installed" + @echo " - pyenv installed" + @echo "" + @echo "After setup, remember to set AIT_CONFIG:" + @echo " export AIT_CONFIG=/path/to/ait-core/config/config.yaml" + +setup-env: + @echo "Installing package with poetry..." + poetry install + +dev-install: + @echo "Installing package with development dependencies..." + poetry install + +install-python: + @echo "Installing required Python versions via pyenv..." + cat .python-version | xargs -I{} pyenv install --skip-existing {} + +pre-commit: + @echo "Installing pre-commit and pre-push hooks..." + pre-commit install && pre-commit install -t pre-push + +setup: setup-env dev-install pre-commit install-python + @echo "" + @echo "Development setup complete!" + @echo "" + @echo "Remember to set AIT_CONFIG:" + @echo " export AIT_CONFIG=$$(pwd)/config/config.yaml" + @echo "" + @echo "Consider adding this to your shell RC file or virtual environment config." + +test: + @echo "Running test suite with pytest..." + pytest + +tox: + @echo "Running full tox build..." + tox + +lint: + @echo "Running linting pipeline..." + tox -e lint + +docs: + @echo "Building documentation..." + poetry run build_sphinx + @echo "" + @echo "Documentation built. Open doc/build/html/index.html to view." + +clean: + @echo "Cleaning build artifacts..." + rm -rf build/ + rm -rf dist/ + rm -rf *.egg-info + rm -rf doc/build/ + rm -rf .tox/ + rm -rf .pytest_cache/ + find . -type d -name __pycache__ -exec rm -rf {} + + find . -type f -name '*.pyc' -delete + find . -type f -name '*.pyo' -delete + +run-tests: + @echo "Running tests for specific Python version (e.g., make run-tests PY=py310)..." + tox -e $(or $(PY),py310) diff --git a/README.rst b/README.rst index ae135fab..aef60a75 100644 --- a/README.rst +++ b/README.rst @@ -51,6 +51,27 @@ As always, we encourage you to install AIT into a virtual environment of your ch - `pyenv `__ so you can easily install different Python versions - `poetry `__ installed either to your specific virtual environment or system-wide, whichever you prefer. +Using Makefile (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The easiest way to set up your development environment is using the provided Makefile. This will handle all the setup steps automatically:: + + make setup + +This will: +- Install the package with development dependencies +- Install pre-commit and pre-push hooks +- Install all required Python versions via pyenv + +After running `make setup`, remember to set your AIT_CONFIG:: + + export AIT_CONFIG=/path/to/ait-core/config/config.yaml + +You can see all available Makefile targets by running:: + + make help + +Alternatively: Manual Installation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Install the package in "editable" mode with all the development dependencies by running the following:: poetry install @@ -74,8 +95,12 @@ Tox ~~~ Use `tox` to run a thorough build of the toolkit that checks test execution across different Python versions, verifies the docs build, runs the linting pipeline, and checks that the repo packages cleanly. Make sure you run `tox` in Poetry's `shell` without another virtual environment active to avoid problems with `tox` finding different python versions for the tests. You can run all of the development tools with:: + # Manual command: tox + # Makefile equivalent: + make tox + You can see the available `tox` test environments by passing `-l` and execute a specific one by passing its name to `-e`. Run `tox -h` for more info. Tests @@ -83,12 +108,20 @@ Tests Use `pytest` to manually run the test suite:: + # Manual command: pytest + # Makefile equivalent: + make test + Or via `tox` for a specific python version:: + # Manual command: tox -e py310 + # Makefile equivalent: + make run-tests PY=py310 + Code Checks ~~~~~~~~~~~ @@ -100,16 +133,24 @@ Individual calls to the tools are configured in ``.pre-commit-config.yaml``. If You can run all the linting tools with tox as well:: + # Manual command: tox -e lint + # Makefile equivalent: + make lint + Documentation ~~~~~~~~~~~~~ AIT uses Sphinx to build its documentation. You can build the documentation with:: + # Manual command: poetry run build_sphinx + # Makefile equivalent: + make docs + To view the documentation, open ``doc/build/html/index.html`` in a web browser. If you just want to check that the docs build is working you can use tox:: tox -e docs