Updated docs to avoid issue with poetry 2.0 not having shell command,…

… cleaned up make command docs and implementation
mlte-team · Jan 6, 2025 · 8f98d2b · 8f98d2b
1 parent e93af42
commit 8f98d2b
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 81 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -26,15 +26,15 @@ jobs:
       - name: Format with black
         run: make check-format
       - name: Lint with flake8
-        run: make check-lint
+        run: make lint
       - name: Typecheck with mypy
-        run: make check-typecheck
+        run: make typecheck
       - name: Check docs
         run: make docs 
       - name: Execute unit tests
         run: make test
       - name: Vet schemas
-        run: make vet
+        run: make check-schema
 
   docker:
     runs-on: ubuntu-latest

diff --git a/Makefile b/Makefile
@@ -1,5 +1,26 @@
 # Automation of various common tasks
 
+# -----------------------------------------------------------------------------
+# Schema Generation / Vetting
+# -----------------------------------------------------------------------------
+
+.PHONY: schema
+schema:
+	poetry run python tools/schema.py generate mlte --verbose
+
+.PHONY: check-schema
+check-schema:
+	poetry run python tools/schema.py vet mlte --verbose
+
+# -----------------------------------------------------------------------------
+# Doc building/checking.
+# -----------------------------------------------------------------------------
+
+# Doc generation.
+.PHONY: docs
+docs:
+	cd docs && poetry run mkdocs build --strict
+
 # -----------------------------------------------------------------------------
 # QA
 # -----------------------------------------------------------------------------
@@ -48,37 +69,13 @@ lint:
 	poetry run flake8 test/
 	poetry run flake8 tools/
 
-.PHONY: check-lint
-check-lint: lint
-
 # Typecheck all source code
 .PHONY: typecheck
 typecheck:
 	poetry run mypy mlte/
 	poetry run mypy test/
 	poetry run mypy tools/
 
-.PHONY: check-typecheck
-check-typecheck: typecheck
-
-# Doc generation.
-.PHONY: docs
-docs:
-	cd docs && poetry run mkdocs build --strict
-
-# Clean cache files
-.PHONY: clean
-clean: 
-	rm -r -f .mypy_cache .pytest_cache
-
-# All quality assurance
-.PHONY: qa
-qa: isort format lint typecheck
-
-# Check all QA tasks
-.PHONY: check
-check: check-isort check-format check-lint check-typecheck
-
 # -----------------------------------------------------------------------------
 # Unit Tests
 # -----------------------------------------------------------------------------
@@ -88,32 +85,28 @@ check: check-isort check-format check-lint check-typecheck
 test:
 	poetry run pytest --cov=mlte test 
 
-# Open coverage results in a browser
-.PHONY: cov-results
-cov-results:
-	coverage html && open htmlcov/index.html
-
 # Demo Jupyter Notebook tests
 .PHONY: demo-test
 demo-test:
 	bash demo/simple/test.sh
 	bash demo/scenarios/test.sh
 
 # -----------------------------------------------------------------------------
-# Schema Generation / Vetting
+# Shorthand actions and checks needed to update and review for pushing.
 # -----------------------------------------------------------------------------
 
-.PHONY: gen
-gen:
-	poetry run python tools/schema.py generate mlte --verbose
+# All quality assurance, as well as schema generation
+.PHONY: qa
+qa: schema isort format lint typecheck docs
 
-.PHONY: vet
-vet:
-	poetry run python tools/schema.py vet mlte --verbose
+# Check all QA tasks
+.PHONY: check-qa
+check-qa: check-schema check-isort check-format lint typecheck docs
 
+# Clean cache files
+.PHONY: clean
+clean: 
+	rm -r -f .mypy_cache .pytest_cache
 
-# -----------------------------------------------------------------------------
-# All actions and checks needed to update and review for pushing.
-# -----------------------------------------------------------------------------
 .PHONY: ci
-ci: clean gen qa docs test
+ci: clean check-qa test
diff --git a/docs/docs/development.md b/docs/docs/development.md
@@ -7,12 +7,9 @@ This document describes some of the development practices used within `MLTE`.
 Use `poetry` to create a Python virtual environment and install the required runtime and development packages. This requires you to install `poetry` on your system first (see https://python-poetry.org/docs/#installation). Once it is installed, you can set up your environment like this (note the inclusion of dev dependency groups below):
 
 ```bash
-$ poetry shell
 $ poetry install --with qa,test,build,docs
 ```
 
-Instead of activating the environment, you can also choose to use `poetry run` to run specific commands.
-
 Now you are ready to start working on `MLTE`!
 
 ## Demos
@@ -33,38 +30,42 @@ $ poetry install --with demo-mac
 
 You can run most project commands (e.g., format sources, lint), in two ways: using the commands in the included Makefile, or running things manually. Using the Makefile works on UNIX-like systems (or anywhere `make` is available), and is shorter to type. Alternatively, you can run each command manually. The sections below describe how to run commands in both ways.
 
-Also, the commands below do not assume that you have your virtual environment enabled. Calling `poetry run` ensures things run in the current virtual environment even if it is not activated. If you manually activate your virtual environment with `poetry shell` (see above), you can run all the commands below without the `poetry run` prefix.
+Also, the commands below do not assume that you have your virtual environment enabled. Calling `poetry run` ensures things run in the current virtual environment even if it is not activated. If you manually activate your virtual environment with, you can run all the commands below without the `poetry run` prefix. 
+
+To manually activate your environment, run:
+
+```bash
+$ source .venv/bin/activate
+```
 
 ### Import Sorting
 
 We sort all Python import code in this project with <a href="https://github.com/PyCQA/isort" target="_blank">`isort`</a>. Assuming you have followed the instructions in the [Quickstart](#quickstart), you can run this locally with:
 
 ```bash
-$ poetry run make isort
+$ make isort
 ```
 
-Alternatively, you can run `isort` manually from the project root:
+If you just want to check the sorting of the imports, without making any changes, you can run this:
 
 ```bash
-$ poetry run isort mlte/
-$ poetry run isort test/
+$ make check-isort
 ```
 
-Code that does not satisfy the formatter will be rejected from pull requests.
+Code that does not satisfy the sorter will be rejected from pull requests.
 
 ### Source Formatting
 
 We format all Python code in this project with the <a href="https://github.com/psf/black" target="_blank">`black`</a> source formatter. Assuming you have followed the instructions in the [Quickstart](#quickstart), you can run the formatter locally with:
 
 ```bash
-$ poetry run make format
+$ make format
 ```
 
-Alternatively, you can run `black` manually from the project root:
+If you just want to check the format, without making any changes, you can run this:
 
 ```bash
-$ poetry run black mlte/
-$ poetry run black test/
+$ make check-format
 ```
 
 Code that does not satisfy the formatter will be rejected from pull requests.
@@ -74,14 +75,7 @@ Code that does not satisfy the formatter will be rejected from pull requests.
 We lint all Python code in this project with the <a href="https://flake8.pycqa.org/en/latest/" target="_blank">`flake8`</a> source linter. Assuming you have followed the instructions in the [Quickstart](#quickstart), you can run the linter locally with:
 
 ```bash
-$ poetry run make lint
-```
-
-Alternatively, you can run `flake8` manually from the project root:
-
-```bash
-$ poetry run flake8 mlte/
-$ poetry run flake8 test/
+$ make lint
 ```
 
 Code that does not satisfy the linter will be rejected from pull requests.
@@ -91,14 +85,7 @@ Code that does not satisfy the linter will be rejected from pull requests.
 We run static type-checking with <a href="http://mypy-lang.org/" target="_blank">`mypy`</a>. Assuming you have followed the instructions in the [Quickstart](#quickstart), you can run the type-checker locally with:
 
 ```bash
-$ poetry run make typecheck
-```
-
-Alternatively, you can run `mypy` manually from the project root:
-
-```bash
-$ poetry run mypy mlte/
-$ poetry run mypy test/
+$ make typecheck
 ```
 
 Code that does not satisfy static type-checking will be rejected from pull requests.
@@ -108,15 +95,15 @@ Code that does not satisfy static type-checking will be rejected from pull reque
 More details in the [Documentation](#documentation) section, but to run document generation from the make command, run this: 
 
 ```bash
-$ poetry run make docs
+$ make docs
 ```
 
 ### Unit Tests
 
 We unit test the `MLTE` library with the <a href="https://docs.pytest.org/en/7.0.x/contents.html" target="_blank">`pytest`</a> package, a test-runner for Python. Assuming you have followed the instructions in the [Quickstart](#quickstart), you can run unit tests locally with:
 
 ```bash
-$ poetry run make test
+$ make test
 ```
 
 Alternatively, you can run the tests manually from the project root:
@@ -130,31 +117,32 @@ Unit test failures result in build failures in CI.
 To test the Juypter notebooks present in the demo folders, run:
 
 ```bash
-$ poetry run make demo-test
+$ make demo-test
 ```
 
 ### Model Schema Generation
 
 The artifacts used by `MLTE` have schemas that are used to validate them. These schemas need to be updated if their internal structure (code) changes. Assuming you have followed the instructions in the [Quickstart](#quickstart), you can do this locally with:
 
 ```bash
-$ poetry run make gen
+$ make schema
 ```
 
-Alternatively, you can run this manually from the project root:
+If you just want to check the schemas, without making any changes, you can run this:
 
 ```bash
-$ poetry run python tools/schema.py generate mlte --verbose
+$ make check-schema
 ```
 
-Unit test failures result in build failures in CI.
+Schema failures result in build failures in CI.
 
 ### Make Shorthand Commands
 
 There are a couple of shorthand commands in the Makefile to run several of the above commands at the same time. The most useful ones include:
 
-* `poetry run make qa`: executes the source sorting, formatting, source linting, and static type checking commands.
-* `poetry run make ci`: executes the same commands as `qa`, but also runs `gen` to generate updated schemas if needed, and runs `test` to execute the unit tests.
+* `make qa`: executes the schema generation, doc check, source sorting, formatting, linting, and static type checking commands.
+* `make check-qa`: executes the schema check, doc check, source sorting check, formatting check, linting check, and static type checking commands.
+* `make ci`: executes the same commands as `check-qa`, but also runs `test` to execute the unit tests, cleaning caches first to better simulate execution in a CI environment.
 
 
 ## Front End