docs: reorganize MkDocs configuration and enhance documentation infrastructure

Author: HosseinNejatiJavaremi

.github/workflows/deploy-docs.yml

@@ -7,7 +7,6 @@ on:
       - docs
     paths:
       - 'docs/**'
-      - 'mkdocs.yml'
       - '.github/workflows/deploy-docs.yml'
 
 permissions:
@@ -47,4 +46,4 @@ jobs:
 
       - name: Deploy documentation
         run: |
-          uv run --group docs mkdocs gh-deploy --force
+          uv run --group docs mkdocs gh-deploy --force -f docs/mkdocs-full.yml

.readthedocs.yaml

@@ -33,7 +33,7 @@ python:
 #  builder: html
 
 mkdocs:
-  configuration: mkdocs.yml
+  configuration: docs/mkdocs.yml
   fail_on_warning: false
 
 # Search settings

Makefile

@@ -150,18 +150,43 @@ ci: ## Run CI pipeline locally
 	$(MAKE) build
 
 .PHONY: docs-serve
-docs-serve: ## Serve MkDocs documentation locally
+docs-serve: ## Serve MkDocs documentation locally (balanced mode)
 	@echo "${BLUE}Serving documentation...${NC}"
-	$(UV) run --group docs mkdocs serve
+	$(UV) run --group docs mkdocs serve -f docs/mkdocs.yml
+
+.PHONY: docs-serve-fast
+docs-serve-fast: ## Serve MkDocs documentation with fast build (for quick iterations)
+	@echo "${BLUE}Serving documentation (fast mode)...${NC}"
+	$(UV) run --group docs mkdocs serve -f docs/mkdocs-fast.yml
+
+.PHONY: docs-serve-no-api
+docs-serve-no-api: ## Serve MkDocs documentation without API auto-generation (fastest)
+	@echo "${BLUE}Serving documentation (no API generation)...${NC}"
+	ENABLE_MKDOCSTRINGS=false $(UV) run --group docs mkdocs serve -f docs/mkdocs.yml
 
 .PHONY: docs-build
-docs-build: ## Build MkDocs documentation
+docs-build: ## Build MkDocs documentation (balanced mode)
 	@echo "${BLUE}Building documentation...${NC}"
-	$(UV) run --group docs mkdocs build
+	$(UV) run --group docs mkdocs build -f docs/mkdocs.yml
+
+.PHONY: docs-build-fast
+docs-build-fast: ## Build MkDocs documentation with fast config
+	@echo "${BLUE}Building documentation (fast mode)...${NC}"
+	$(UV) run --group docs mkdocs build -f docs/mkdocs-fast.yml
+
+.PHONY: docs-build-full
+docs-build-full: ## Build MkDocs documentation with full features (for production)
+	@echo "${BLUE}Building documentation (full mode)...${NC}"
+	$(UV) run --group docs mkdocs build -f docs/mkdocs-full.yml --clean
+
+.PHONY: docs-time
+docs-time: ## Time the documentation build
+	@echo "${BLUE}Timing documentation build...${NC}"
+	time $(UV) run --group docs mkdocs build -f docs/mkdocs.yml
 
 .PHONY: docs-deploy
 docs-deploy: ## Deploy MkDocs to GitHub Pages
 	@echo "${BLUE}Deploying documentation...${NC}"
-	$(UV) run --group docs mkdocs gh-deploy --force
+	$(UV) run --group docs mkdocs gh-deploy --force -f docs/mkdocs-full.yml
 
 .DEFAULT_GOAL := help

README.md

@@ -28,17 +28,24 @@ ArchiPy is a Python framework designed to provide a standardized, scalable, and
 
 ## 📋 Table of Contents
 
-- [Goals](#-goals)
-- [Features](#-features)
-- [Prerequisites](#-prerequisites)
-- [Installation](#-installation)
-- [Usage](#-usage)
-- [Development](#-development)
-- [Contributing](#-contributing)
-- [License](#-license)
-- [Sponsors](#-sponsors)
-- [Contact](#-contact)
-- [Links](#-links)
+- [ArchiPy - Architecture + Python](#archipy---architecture--python)
+  - [**Structured Python Development Made Simple**](#structured-python-development-made-simple)
+  - [📋 Table of Contents](#-table-of-contents)
+  - [🎯 Goals](#-goals)
+  - [✨ Features](#-features)
+  - [🛠️ Prerequisites](#️-prerequisites)
+  - [📥 Installation](#-installation)
+  - [🎯 Usage](#-usage)
+    - [Optional Dependencies](#optional-dependencies)
+  - [🛠️ Development](#️-development)
+    - [Quick Commands](#quick-commands)
+  - [🤝 Contributing](#-contributing)
+  - [📄 License](#-license)
+  - [🙌 Sponsors](#-sponsors)
+  - [📞 Contact](#-contact)
+  - [🔗 Links](#-links)
+  - [📚 Documentation](#-documentation)
+    - [Quick Start](#quick-start)
 
 ---
 
@@ -174,21 +181,27 @@ ArchiPy's documentation has been migrated from Sphinx to MkDocs for improved rea
 - **Improved Navigation**: Intuitive organization and search
 - **Clearer Examples**: Expanded code samples with explanations
 - **API Reference**: Auto-generated from source code docstrings
+- **Performance Optimized**: Multiple build modes for fast iteration
 
-To run the documentation locally:
+### Quick Start
 
 ```bash
 # Install documentation dependencies
 uv sync --group docs
 
-# Serve documentation locally
+# Fast mode for quick iterations (10-20s builds)
+make docs-serve-fast
+
+# Balanced mode for regular work (30-60s builds)
 make docs-serve
 
-# Build documentation
-make docs-build
+# Full production build (2-5min, all features)
+make docs-build-full
 
 # Deploy to GitHub Pages
 make docs-deploy
 ```
 
+**See [DOCS_QUICKSTART.md](DOCS_QUICKSTART.md) for more commands and tips.**
+
 [View the latest documentation](https://syntaxarc.github.io/ArchiPy/)