Skip to content

Commit e118107

Browse files
LouisTierLouisTier
committed
chore: update Makefile and documentation for improved clarity and organization
- Enhanced the Makefile by adding new targets for installation and testing, improving usability for developers. - Updated the help command in the Makefile to provide clearer examples and descriptions of available commands. - Added a new PDF reference to the .gitignore to prevent unnecessary tracking of generated files. - Revised the README to reflect changes in project structure and provide updated links to documentation and resources. - Removed deprecated references and improved the overall organization of the README for better readability.
1 parent 4d5d709 commit e118107

File tree

12 files changed

+1464
-148
lines changed

12 files changed

+1464
-148
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
# notebooks/results/
44
torchsom/logger.py
55
logos/
6+
assets/torchsom_jmlr.pdf
67

78
.github/workflows/security.yml
89

‎Makefile‎

Lines changed: 231 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,290 @@
1-
# TorchSOM Development Makefile: provides convenient commands for local development and testing
2-
# Run `make help` to see all available commands
1+
# TorchSOM Development Makefile
2+
# Run `make help` to see available commands
33

4-
.PHONY: help install test test-quick lint format security docs clean all
4+
# Note on pyproject.toml integration:
5+
# - black, isort, ruff: read [tool.black], [tool.isort], [tool.ruff] automatically
6+
# - mypy: must pass --config-file pyproject.toml
7+
# - pytest: reads --cov-config=pyproject.toml for coverage config
8+
# - bandit: does NOT read TOML, uses CLI options only
9+
# - interrogate: can use --config if needed
10+
# - sphinx-build: uses conf.py, TOML not involved
11+
# - pip-compile: reads dependencies from pyproject.toml
12+
13+
.PHONY: help install test test-quick test-gpu test-integration lint format security docs clean clean-docs precommit complexity dependencies ci all publish fix check coverage install-dev install-tests install-security install-linting install-docs install-precommit install-all test-coverage check-black check-isort check-ruff check-mypy lint-all format-black format-isort format-ruff format-all check-docstrings measure-docstrings-coverage build-docs clean-build clean-test clean-lint clean-security clean-python clean-all check-cc check-mi complexity-all build-dist upload-dist
14+
15+
# --------------------------
16+
# Aliases for commands
17+
# --------------------------
18+
19+
install: install-all
20+
cov: test-coverage
21+
check: lint-all
22+
fix: format-all
23+
complexity: complexity-all
24+
clean: clean-all
25+
26+
# --------------------------
27+
# Default help target
28+
# --------------------------
529

6-
# Default target
730
help: ## Show this help message
831
@echo "TorchSOM Development Commands:"
932
@echo ""
10-
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-15s\033[0m %s\n", $$1, $$2}'
33+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-20s\033[0m %s\n", $$1, $$2}'
1134
@echo ""
1235
@echo "Examples:"
13-
@echo " make install # Install development dependencies"
14-
@echo " make test # Run all tests with coverage"
15-
@echo " make lint # Run all code quality checks"
16-
@echo " make format # Auto-fix formatting issues"
17-
@echo " make all # Run everything (like CI)"
18-
19-
install: ## Install development dependencies
20-
@echo "📦 Installing development dependencies..."
21-
pip install -e ".[dev, tests, security, linting, docs]"
36+
@echo ""
37+
@echo " make install # Install development dependencies"
38+
@echo " make test # Run all tests with coverage"
39+
@echo " make lint # Run all code quality checks"
40+
@echo " make format # Auto-fix formatting issues"
41+
@echo " make all # Run full CI simulation"
42+
@echo ""
43+
44+
# --------------------------
45+
# Environment Setup
46+
# --------------------------
47+
48+
install-dev: ## Install development dependencies
49+
pip install -e ".[dev]"
50+
51+
install-tests: ## Install test dependencies
52+
pip install -e ".[tests]"
53+
54+
install-security: ## Install security dependencies
55+
pip install -e ".[security]"
56+
57+
install-linting: ## Install linting dependencies
58+
pip install -e ".[linting]"
59+
60+
install-docs: ## Install documentation dependencies
61+
pip install -e ".[docs]"
62+
63+
install-precommit: ## Install pre-commit dependencies
2264
pip install pre-commit
2365
pre-commit install
2466

25-
TESTS ?= tests/unit/ # tests/unit/ or tests/unit/test_som.py::TestInputValidation
26-
test: ## Run all tests with coverage
27-
@echo "🧪 Running tests with coverage..."
28-
pytest $(TESTS) -v \
29-
--cov=torchsom \
30-
--cov-report=term-missing \
31-
--cov-report=html \
32-
--cov-config=pyproject.toml \
33-
--junit-xml=junit.xml \
34-
-m "unit or gpu"
35-
# -m "not unit and not gpu"
36-
# -v verbose, -x exit on first failure, -m marker: run only tests with the corresponding markers
37-
test-quick: ## Run tests without coverage (faster)
38-
@echo "⚡ Running quick tests..."
39-
pytest tests/unit/ -v -x -m "unit and not gpu"
67+
install-all: ## Install all dependencies
68+
@echo "📦 Installing all dependencies..."
69+
$(MAKE) install-dev
70+
$(MAKE) install-tests
71+
$(MAKE) install-security
72+
$(MAKE) install-linting
73+
$(MAKE) install-docs
74+
$(MAKE) install-precommit
75+
76+
# --------------------------
77+
# Testing
78+
# --------------------------
79+
80+
TESTS ?= tests/unit/ # Default test path
4081

4182
test-gpu: ## Run GPU tests (requires CUDA)
4283
@echo "🖥️ Running GPU tests..."
43-
pytest tests/unit/ -v -m "gpu"
44-
test-integration: ## Run GPU tests (requires CUDA)
84+
pytest $(TESTS) -v -x -m "gpu"
85+
# -v verbose, -x exit on first failure, -m marker: run only tests with the corresponding markers
86+
87+
test-integration: ## Run integration tests
4588
@echo "🖥️ Running integration tests..."
46-
pytest tests/unit/ -v -m "integration"
89+
pytest $(TESTS) -v -m "integration"
4790

48-
lint: ## Run all code quality checks
49-
@echo "🔍 Running code quality checks..."
50-
@echo " 🎨 Checking code formatting..."
91+
test-coverage: ## Run all tests with coverage
92+
@echo "🧪 Running tests with coverage..."
93+
pytest
94+
# pytest $(TESTS) -v \
95+
# --cov=torchsom \
96+
# --cov-report=term-missing \
97+
# --cov-report=html \
98+
# --cov-config=pyproject.toml \
99+
# --junit-xml=junit.xml \
100+
# -m "unit or gpu"
101+
102+
# --------------------------
103+
# Code Quality
104+
# --------------------------
105+
106+
check-black: ## Run black check
51107
black --check --diff torchsom/ tests/
52-
@echo " 📦 Checking import sorting..."
108+
109+
check-isort: ## Run isort check
53110
isort --check-only --diff torchsom/ tests/
54-
@echo " 🔍 Running linter..."
111+
112+
check-ruff: ## Run ruff check
55113
ruff check torchsom/ tests/
56-
@echo " 🎯 Type checking..."
114+
115+
check-mypy: ## Run mypy check
57116
mypy torchsom/ --ignore-missing-imports --strict
117+
118+
lint-all: ## Run all code quality checks
119+
@echo "🔍 Running code quality checks (formatting, sorting, linting, type checking)..."
120+
$(MAKE) check-black
121+
$(MAKE) check-isort
122+
$(MAKE) check-ruff
123+
$(MAKE) check-mypy
58124
@echo "✅ All quality checks passed!"
59-
# ruff check torchsom/ tests/ => read-only mode, report violations without modifications
60-
# ruff check torchsom/ tests/ --fix => fix safe, non-destructive violations
61-
# ruff check torchsom/ tests/ --fix --unsafe-fixes => fix unsafe, potentially destructive violations (might need review)
62-
# ruff check torchsom/ tests/ --fix --unsafe-fixes --diff => fix unsafe, potentially destructive violations (might need review)
63-
# mypy torchsom/ --ignore-missing-imports => Skip checking for modules it cannot find
64-
65-
format: ## Auto-fix formatting and import issues
66-
@echo "🎨 Auto-fixing code formatting..."
125+
126+
format-black: ## Auto-fix black formatting
67127
black torchsom/ tests/
128+
129+
format-isort: ## Auto-fix isort formatting
68130
isort torchsom/ tests/
131+
132+
format-ruff: ## Auto-fix ruff formatting
69133
ruff check --fix torchsom/ tests/
134+
135+
format-all: ## Auto-fix formatting and imports
136+
@echo "🎨 Auto-fixing code formatting, imports, and linting..."
137+
$(MAKE) format-black
138+
$(MAKE) format-isort
139+
$(MAKE) format-ruff
70140
@echo "✅ Formatting applied!"
71141

142+
precommit: ## Run pre-commit hooks on all files
143+
@echo "🔧 Running pre-commit hooks..."
144+
pre-commit run --all-files
145+
146+
# --------------------------
147+
# Security
148+
# --------------------------
149+
72150
security: ## Run security scans
73151
@echo "🔒 Running security scans..."
74-
@echo "🛡️ Bandit security check (library code)..."
75152
bandit -r torchsom/ --exclude tests --skip B101,B311,B601
76-
@echo "🛡️ Bandit security check (tests, skip assert rule)..."
77153
bandit -r tests --skip B101,B311,B601
78154
@echo "✅ Security scans completed!"
79-
# @echo "🔍 Pip audit..."
80-
# pip-audit
81-
# @echo "⚠️ Safety vulnerability check..."
82-
# safety scan
83155

84-
docs: ## Check documentation quality
85-
@echo "📚 Checking documentation..."
86-
@echo " 📝 Docstring style..."
156+
# --------------------------
157+
# Documentation
158+
# --------------------------
159+
160+
check-docstrings: ## Check docstrings
87161
pydocstyle torchsom/ --convention=google
88-
@echo " 📊 Docstring coverage..."
162+
163+
measure-docstrings-coverage: ## Assess docstring coverage
89164
interrogate torchsom/ --verbose --ignore-init-method --ignore-magic --ignore-module --fail-under=80
90-
@echo " 🏗️ Building HTML documentation..."
91-
sphinx-build -b html docs/source/ docs/build/html
165+
166+
build-docs: ## Build documentation
167+
sphinx-build -b html -W --keep-going docs/source/ docs/build/html
168+
# sphinx-build -b html docs/source/ docs/build/html
169+
170+
docs: ## Check documentation quality
171+
@echo "📚 Checking documentation..."
172+
$(MAKE) check-docstrings
173+
$(MAKE) measure-docstrings-coverage
174+
$(MAKE) build-docs
92175
@echo "✅ Documentation checks and build complete!"
93176

177+
# --------------------------
178+
# Cleanup
179+
# --------------------------
180+
94181
clean-docs: ## Remove Sphinx build artifacts
95182
@echo "🧹 Cleaning documentation build..."
96183
rm -rf docs/build/html/
97-
@echo "✅ Cleaned!"
98-
# rm -rf build/*
99-
100-
precommit: ## Run pre-commit hooks on all files
101-
@echo "🔧 Running pre-commit hooks..."
102-
pre-commit run --all-files
184+
@echo "✅ Documentation cleaned!"
103185

104-
clean: ## Clean up generated files
105-
@echo "🧹 Cleaning up..."
186+
clean-build: ## Remove build and distribution artifacts
187+
@echo "🧹 Cleaning build artifacts..."
106188
rm -rf build/ dist/ *.egg-info/
189+
@echo "✅ Build artifacts cleaned!"
190+
191+
clean-test: ## Remove test and coverage artifacts
192+
@echo "🧹 Cleaning test artifacts..."
107193
rm -rf .pytest_cache/ .coverage htmlcov/
108-
rm -rf .mypy_cache/ .ruff_cache/
109194
rm -f junit.xml coverage.xml
195+
@echo "✅ Test artifacts cleaned!"
196+
197+
clean-lint: ## Remove linting and type checking cache
198+
@echo "🧹 Cleaning linting cache..."
199+
rm -rf .mypy_cache/ .ruff_cache/
200+
@echo "✅ Linting cache cleaned!"
201+
202+
clean-security: ## Remove security scan reports
203+
@echo "🧹 Cleaning security reports..."
110204
rm -f bandit-report.json safety-report.json pip-audit-report.json
111-
find . -type d -name __pycache__ -delete
205+
@echo "✅ Security reports cleaned!"
206+
207+
clean-python: ## Remove Python cache files
208+
@echo "🧹 Cleaning Python cache..."
112209
find . -type f -name "*.pyc" -delete
113-
@echo "✅ Cleanup completed!"
210+
find . -type d -name __pycache__ -delete
211+
@echo "✅ Python cache cleaned!"
114212

115-
complexity: ## Run complexity analysis: cc = cyclomatic complexity, mi = maintainability index
116-
@echo "🔍 Running complexity analysis..."
213+
clean-all: ## Clean up all generated files (runs all clean- commands)
214+
@echo "🧹 Cleaning up all generated files..."
215+
@echo ""
216+
$(MAKE) clean-build
217+
$(MAKE) clean-test
218+
$(MAKE) clean-lint
219+
$(MAKE) clean-security
220+
$(MAKE) clean-python
221+
$(MAKE) clean-docs
222+
@echo ""
223+
@echo "✅ All cleanup completed!"
224+
225+
# --------------------------
226+
# Complexity Analysis
227+
# --------------------------
228+
229+
check-cc: ## Check cyclomatic complexity
117230
radon cc torchsom/ --show-complexity --min B
231+
232+
check-mi: ## Check maintainability index
118233
radon mi torchsom/ --show --min B
234+
235+
complexity-all: ## Run cyclomatic complexity and maintainability analysis
236+
@echo "🔍 Running complexity analysis..."
237+
$(MAKE) check-cc
238+
$(MAKE) check-mi
119239
@echo "✅ Complexity analysis completed!"
120240

121-
dependencies: ## Check for dependency conflicts: super super long
241+
# --------------------------
242+
# Dependencies
243+
# --------------------------
244+
245+
dependencies: ## Check for dependency conflicts: : super long with pip-compile
122246
@echo "🔍 Checking for dependency conflicts..."
123-
pip-compile pyproject.toml --dry-run --verbose
247+
pip check
124248
@echo "✅ Dependency checks completed!"
249+
# pip-compile pyproject.toml --dry-run --verbose
250+
251+
# --------------------------
252+
# CI / Full Pipeline
253+
# --------------------------
125254

126-
ci: format lint security complexity docs ## Run CI pipeline (full CI simulation)
255+
ci: ## Run CI pipeline (without tests)
127256
@echo ""
128-
@echo "🎉 All checks passed (without tests)! Ready to push to GitHub!"
257+
$(MAKE) check
258+
$(MAKE) fix
259+
$(MAKE) security
260+
$(MAKE) complexity
261+
$(MAKE) dependencies
262+
$(MAKE) docs
263+
@echo "🎉 All checks passed (without tests)! Ready to push!"
129264

130-
all: format lint security complexity docs test ## Run everything (full CI simulation)
265+
all: ## Run full CI simulation (includes tests)
266+
@echo ""
267+
$(MAKE) ci
268+
$(MAKE) cov
131269
@echo ""
132-
@echo "🎉 All checks passed! Ready to push to GitHub!"
270+
@echo "🎉 All checks passed! Ready to push!"
133271

134-
publish: ## Publish to PyPI
135-
@echo "📦 Publishing to PyPI..."
136-
# export $(cat .env | xargs)
272+
# --------------------------
273+
# Publishing
274+
# --------------------------
275+
276+
build-dist: ## Build distribution
137277
python -m build
278+
279+
upload-dist: ## Upload distribution
138280
twine upload dist/*
139-
@echo "✅ Published to PyPI!"
140281

141-
# Quick commands for common tasks, defining aliases for the most common commands (alias: common_command)
142-
fix: format
143-
check: lint
144-
coverage: test
282+
publish: ## Build and upload to PyPI (manually but is triggered by .github/workflows/release.yml with tag modifications)
283+
@echo "📦 Publishing to PyPI..."
284+
@bash -c '\
285+
source .env; \
286+
export TWINE_USERNAME TWINE_PASSWORD; \
287+
$(MAKE) build-dist; \
288+
$(MAKE) upload-dist \
289+
'
290+
@echo "✅ Published to PyPI!"

0 commit comments

Comments
 (0)