test+docs

Author: nenuadrian

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs (GitHub Pages)
+
+on:
+  push:
+    branches: ["master"]
+    paths:
+      - "README.md"
+      - "includes/**"
+      - "tests/**"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "scripts/generate-mkdocs-material.sh"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Generate Docs Material
+        run: ./scripts/generate-mkdocs-material.sh
+
+      - name: Build Site
+        run: mkdocs build --strict
+
+      - name: Upload Pages Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/php.yml

@@ -1,4 +1,4 @@
-name: PHP Composer
+name: PHP Tests
 
 on:
   push:
@@ -10,31 +10,33 @@ permissions:
   contents: read
 
 jobs:
-  build:
-
+  test:
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
 
-    - name: Cache Composer packages
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: '8.3'
+        tools: composer:v2
+        coverage: none
+
+    - name: Get Composer cache directory
       id: composer-cache
-      uses: actions/cache@v3
+      run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
+
+    - name: Cache Composer downloads
+      uses: actions/cache@v4
       with:
-        path: vendor
-        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+        path: ${{ steps.composer-cache.outputs.dir }}
+        key: ${{ runner.os }}-php83-composer-${{ hashFiles('composer.json', 'composer.lock') }}
         restore-keys: |
-          ${{ runner.os }}-php-
+          ${{ runner.os }}-php83-composer-
 
     - name: Install dependencies
-      run: composer install --prefer-dist --no-progress
-
-    - name: Test
-      run: ./includes/vendor/phpunit/phpunit/phpunit tests
-      
-
-    # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
-    # Docs: https://getcomposer.org/doc/articles/scripts.md
+      run: composer install --prefer-dist --no-interaction --no-progress
 
-    # - name: Run test suite
-    #   run: composer run-script test
+    - name: Run tests
+      run: composer test

.gitignore

@@ -6,3 +6,4 @@ composer.lock
 
 .DS_Store
 **/.DS_Store
+site/

composer.json

@@ -24,5 +24,8 @@
     "require-dev": {
         "overtrue/phplint": "^5.3",
         "phpunit/phpunit": "^9.5"
+    },
+    "scripts": {
+        "test": "phpunit tests"
     }
 }

docs/architecture/routing.md

@@ -0,0 +1,23 @@
+# Request Routing
+
+Routing is handled in `public_html/index.php` by mapping URL segments to files inside `includes/modules/`.
+
+## Lifecycle Summary
+
+1. Bootstrap Composer autoload and Smarty.
+2. Parse request path into a module key and key/value parameters.
+3. Resolve module file from `includes/modules/*.php`.
+4. Include shared boot logic from `includes/header.php`.
+5. Execute module and render Smarty templates.
+
+## Route Resolution Rules
+
+- Missing module defaults to `main/main`.
+- If `includes/database_info.php` is missing, routing is forced to `setup`.
+- If route points to a folder (example: `grid`), runtime attempts `includes/modules/grid/grid.php`.
+
+## Data Passed To Modules
+
+- Parsed path pairs are stored in `$GET`.
+- Current module path is tracked in `$GET['currentPage']`.
+- Template variables are assembled in `$tVars` and rendered at the end of the request.

docs/index.md

@@ -0,0 +1,21 @@
+# Secret Republic V3 Documentation
+
+This documentation is generated from project sources, with material extracted from `README.md`, `includes/`, and `tests/`.
+
+## Repository Snapshot
+
+- PHP modules discovered: **79**
+- PHP class files discovered: **24**
+- Constants/config files discovered: **7**
+- PHPUnit test files discovered: **4**
+
+## What Is Included
+
+- README-based project documentation and setup notes
+- Routing and request lifecycle notes from `public_html/index.php`
+- Auto-generated module/class/constants/test inventories
+
+## Next Steps
+
+- Use the navigation sidebar to explore generated references.
+- Update code and rerun `./scripts/generate-mkdocs-material.sh`.