Enhancing documentation

2025-09-20 22:39:12 +02:00
parent 5996cecc42
commit a26f8086f8
22 changed files with 2176 additions and 5221 deletions
--- a/132
+++ b/132
@@ -1,5 +1,5 @@
 # Comprehensive Makefile for LetzShop API (Windows Compatible)
-.PHONY: install install-test install-dev install-all dev test test-unit test-integration test-coverage test-fast test-slow test-auth test-products test-stock lint format check docker-build docker-up docker-down migrate clean check-tools setup setup-test
+.PHONY: install install-test install-dev install-docs install-all dev test test-unit test-integration test-coverage test-fast test-slow test-auth test-products test-stock lint format check docker-build docker-up docker-down migrate clean check-tools setup setup-test docs docs-serve docs-build docs-deploy docs-clean help

 # Check if required tools are installed (Windows compatible)
 check-tools:
@@ -8,6 +8,9 @@ check-tools:
 	@where flake8 >nul 2>&1 || (echo flake8 is required but not installed. Run 'make install-dev' first. && exit 1)
 	@where mypy >nul 2>&1 || (echo mypy is required but not installed. Run 'make install-dev' first. && exit 1)

+check-docs-tools:
+	@where mkdocs >nul 2>&1 || (echo mkdocs is required but not installed. Run 'make install-docs' first. && exit 1)
+
 # Development setup
 install:
 	pip install -r requirements.txt
@@ -19,14 +22,68 @@ install-dev:
 	pip install -r requirements.txt
 	pip install -r tests/requirements-test.txt
 	pip install -r requirements-dev.txt
+
+install-docs:
 	pip install -r requirements-docs.txt

-install-all: install install-test install-dev
+install-all: install install-test install-dev install-docs

-# Development server
+# Development servers
 dev:
 	uvicorn main:app --reload --host 0.0.0.0 --port 8000

+dev-with-docs:
+	@echo Starting API server and documentation server...
+	@start /B uvicorn main:app --reload --host 0.0.0.0 --port 8000
+	@timeout /t 3 >nul
+	@mkdocs serve --dev-addr=0.0.0.0:8001
+
+# Documentation commands
+docs: docs-serve
+
+docs-serve:
+	@echo Starting MkDocs development server...
+	mkdocs serve --dev-addr=0.0.0.0:8001
+
+docs-build:
+	@echo Building documentation site...
+	mkdocs build --clean --strict
+
+docs-build-quiet:
+	@echo Building documentation (quiet)...
+	mkdocs build --clean --quiet
+
+docs-deploy:
+	@echo Deploying documentation to GitHub Pages...
+	mkdocs gh-deploy --clean
+
+docs-deploy-force:
+	@echo Force deploying documentation to GitHub Pages...
+	mkdocs gh-deploy --clean --force
+
+docs-update:
+	@echo Updating documentation with API information...
+	python scripts/update_docs.py
+
+docs-clean:
+	@echo Cleaning documentation build files...
+	@if exist site rmdir /s /q site
+	@echo Documentation build files cleaned!
+
+docs-check:
+	@echo Checking documentation for issues...
+	mkdocs build --strict --verbose
+
+docs-help:
+	mkdocs --help
+
+# Combined development environment
+dev-full: dev-with-docs
+	@echo Development environment ready!
+	@echo API server: http://localhost:8000
+	@echo API docs: http://localhost:8000/docs
+	@echo Documentation: http://localhost:8001
+
 # Testing commands
 test:
 	pytest tests/ -v
@@ -117,6 +174,15 @@ deploy-staging:
 deploy-prod:
 	docker-compose -f docker-compose.prod.yml up -d

+# Documentation deployment workflow
+docs-publish: docs-build docs-deploy
+	@echo Documentation published successfully!
+	@echo Visit: https://yourusername.github.io/letzshop-import/
+
+docs-preview: docs-build
+	@echo Opening documentation preview...
+	@start site\index.html
+
 # Clean up (Windows compatible)
 clean:
 	@if exist htmlcov rmdir /s /q htmlcov
@@ -126,28 +192,63 @@ clean:
 	@for /d /r . %%d in (__pycache__) do @if exist "%%d" rmdir /s /q "%%d"
 	@del /s /q *.pyc 2>nul || echo No .pyc files found

+clean-all: clean docs-clean
+	@echo All build artifacts cleaned!
+
 # Development workflow shortcuts
-setup: install-dev migrate-up
+setup: install-all migrate-up
 	@echo Development environment setup complete!
+	@echo Run 'make dev-full' to start both API and documentation servers

 setup-test: install-test
 	@echo Test environment setup complete!

+setup-docs: install-docs
+	@echo Documentation environment setup complete!
+	@echo Run 'make docs-serve' to start documentation server
+
 full-test: format lint test-coverage
 	@echo Full test suite completed!

+# Quality assurance workflow
+qa: format lint test-coverage docs-check
+	@echo Quality assurance checks completed!
+
+# Release workflow
+release-check: qa docs-build
+	@echo Release readiness check completed!
+
 # Help command
 help:
 	@echo Available commands:
+	@echo.
+	@echo === SETUP ===
 	@echo   install       - Install production dependencies
 	@echo   install-test  - Install test dependencies only
 	@echo   install-dev   - Install all development dependencies
+	@echo   install-docs  - Install documentation dependencies
 	@echo   install-all   - Install everything
 	@echo   setup         - Complete development setup
 	@echo   setup-test    - Setup test environment only
-	@echo   dev           - Start development server
+	@echo   setup-docs    - Setup documentation environment
 	@echo.
-	@echo Testing:
+	@echo === DEVELOPMENT ===
+	@echo   dev           - Start development server (API only)
+	@echo   dev-with-docs - Start both API and documentation servers
+	@echo   dev-full      - Start full development environment with info
+	@echo.
+	@echo === DOCUMENTATION ===
+	@echo   docs          - Start documentation development server (alias for docs-serve)
+	@echo   docs-serve    - Start MkDocs development server
+	@echo   docs-build    - Build documentation site
+	@echo   docs-deploy   - Deploy documentation to GitHub Pages
+	@echo   docs-publish  - Build and deploy documentation
+	@echo   docs-preview  - Build and open documentation locally
+	@echo   docs-update   - Update docs with API information
+	@echo   docs-check    - Check documentation for issues
+	@echo   docs-clean    - Clean documentation build files
+	@echo.
+	@echo === TESTING ===
 	@echo   test          - Run all tests
 	@echo   test-unit     - Run unit tests only
 	@echo   test-integration - Run integration tests only
@@ -156,22 +257,33 @@ help:
 	@echo   test-slow     - Run slow tests only
 	@echo   full-test     - Format, lint, and test with coverage
 	@echo.
-	@echo Code Quality:
+	@echo === CODE QUALITY ===
 	@echo   format        - Format code with black and isort
 	@echo   lint          - Run linting with flake8 and mypy
 	@echo   check         - Format and lint code
 	@echo   ci            - Full CI pipeline (format, lint, test)
+	@echo   qa            - Quality assurance (format, lint, test, docs check)
 	@echo.
-	@echo Database:
+	@echo === DATABASE ===
 	@echo   migrate-up    - Run database migrations
 	@echo   migrate-down  - Rollback last migration
 	@echo   migrate-reset - Reset and rerun all migrations
 	@echo.
-	@echo Docker:
+	@echo === DOCKER ===
 	@echo   docker-build  - Build Docker containers
 	@echo   docker-up     - Start Docker containers
 	@echo   docker-down   - Stop Docker containers
 	@echo   docker-restart - Restart Docker containers
 	@echo.
-	@echo Cleanup:
+	@echo === CLEANUP ===
 	@echo   clean         - Remove test artifacts and cache files
+	@echo   clean-all     - Remove all build artifacts (including docs)
+	@echo.
+	@echo === WORKFLOWS ===
+	@echo   release-check - Complete release readiness check
+	@echo.
+	@echo === QUICK START ===
+	@echo   make setup           # First time setup
+	@echo   make dev-full        # Start development environment
+	@echo   make docs-serve      # Start documentation server
+	@echo   make qa              # Run quality checks