Merge pull request #19 from SyntaxArc/docs

Migrate to MkDocs

Author: rabbitix

.github/workflows/deploy-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+      - docs
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/deploy-docs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for proper versioning
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          cache: 'pip'
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: 2.0.0
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Load cached dependencies
+        id: cached-poetry-dependencies
+        uses: actions/cache@v3
+        with:
+          path: .venv
+          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: |
+          poetry install --with docs
+
+      - name: Configure Git user
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Deploy documentation
+        run: |
+          poetry run mkdocs gh-deploy --force

.readthedocs.yaml

@@ -10,16 +10,12 @@ build:
   tools:
     python: "3.13"  # Using a stable Python version supported by ReadTheDocs
   jobs:
-    pre_build:
-      # Generate API docs from source before building
-      - cd docs && sphinx-apidoc -o source/ ../archipy -f -e -M -T
     post_create_environment:
       # Install poetry and configure it
       - pip install poetry
       - poetry config virtualenvs.create false
     post_install:
-      # Ensure we have the latest documentation tools
-      - pip install --upgrade sphinx sphinx-rtd-theme sphinx-autodoc-typehints sphinx-autoapi
+      - poetry install --with docs
 
 # Use the latest version of build system
 python:
@@ -28,21 +24,22 @@ python:
       path: .
       extra_requirements:
         - docs
-    - requirements: docs/requirements.txt
+    - requirements: docs/source/requirements.txt
 
 # Build documentation with maximum extraction settings
-sphinx:
-  configuration: docs/source/conf.py
-  fail_on_warning: false  # Set to true once your docs are stable
-  builder: html
-
+#sphinx:
+#  configuration: docs/source/conf.py
+#  fail_on_warning: false  # Set to true once your docs are stable
+#  builder: html
 
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
 
 # Search settings
 search:
   ranking:
     # These paths will be ranked higher in search results
     api_reference/*: 2
-    usage.rst: 3
-    installation.rst: 3
-    architecture.rst: 2
+    installation.md: 3
+    architecture.md: 2

CLAUDE.md

@@ -0,0 +1,22 @@
+# ArchiPy Development Guide
+
+## Commands
+- **Setup**: `poetry install --with dev --all-extras`
+- **Format**: `make format` (Black, 120 char line length)
+- **Lint**: `make lint` (Ruff + MyPy)
+- **Test**: `make behave` (all tests)
+- **Single test**: `poetry run behave features/file_name.feature`
+- **Specific scenario**: `poetry run behave features/file_name.feature:line_number`
+- **All checks**: `make check` (lint + test)
+- **Pre-commit hooks**: `make pre-commit`
+
+## Code Style
+- **Imports**: Use strict section order: `future → stdlib → third-party → first-party → local`
+- **Typing**: Strict typing required with MyPy (`disallow_untyped_defs=true`)
+- **Quotes**: Double quotes for inline strings, single quotes for multiline
+- **Docstrings**: Google-style docstrings required for all public APIs
+- **Naming**: Snake case for functions/vars, PascalCase for classes (enforced by Ruff)
+- **Error handling**: Use specific exception types, add to custom_errors.py when needed
+- **Line length**: 120 characters maximum
+- **Complexity**: Keep McCabe complexity below 10
+- **Formatting**: Files end with newline, consistent indent (4 spaces)

Makefile

@@ -140,4 +140,19 @@ ci: ## Run CI pipeline locally
 	$(MAKE) test
 	$(MAKE) build
 
+.PHONY: docs-serve
+docs-serve: ## Serve MkDocs documentation locally
+	@echo "${BLUE}Serving documentation...${NC}"
+	$(POETRY) run mkdocs serve
+
+.PHONY: docs-build
+docs-build: ## Build MkDocs documentation
+	@echo "${BLUE}Building documentation...${NC}"
+	$(POETRY) run mkdocs build
+
+.PHONY: docs-deploy
+docs-deploy: ## Deploy MkDocs to GitHub Pages
+	@echo "${BLUE}Deploying documentation...${NC}"
+	$(POETRY) run mkdocs gh-deploy --force
+
 .DEFAULT_GOAL := help