🔍 Hierarchy Discovery Integration Guide¶

Status: 🟡 PREPARED - NOT YET ENABLED

This guide documents how to enable automatic XX_YY_ZZ hierarchy discovery in the MkDocs container.

📋 Overview¶

The hierarchy discovery script automatically scans the AudioLab repository for directories following the XX_YY_ZZ_Name pattern and generates MkDocs navigation structure.

Current Status: - ✅ Script created and corrected for container environment - ✅ Dockerfile prepared with script support - 🔴 Feature is DISABLED by default

🔧 What Was Fixed¶

Original Problem¶

The original discover_hierarchy.py script failed in containers because:

Path assumption: Assumed host filesystem structure

# ❌ Old (broken in container)
repo_root = script_path.parents[5]

Hardcoded output paths: Not container-aware

# ❌ Old (broken in container)
output_file = script_path.parent / 'nav_structure.yml'

Container-Optimized Solution¶

The corrected script now:

Smart path detection:

# ✅ New (container-aware)
def find_repo_root(start_path: Path) -> Path:
    # Strategy 1: Container environment detection
    docs_path = Path('/docs')
    if docs_path.exists():
        # /docs is mounted from 07_META/03_documentation
        # So repo root is 2 levels up
        return docs_path.parent.parent

    # Strategy 2: Git repository detection
    # ... (fallback strategies)

Container-aware output:

# ✅ New (container paths)
def get_output_paths() -> Tuple[Path, Path]:
    nav_file = Path('/docs/nav_structure.yml')
    mkdocs_file = Path('/docs/mkdocs.yml')
    return nav_file, mkdocs_file

Multiple detection strategies:
Container mount detection (/docs exists)
Git repository detection (.git directory)
Marker file detection (vcpkg.json, expected directories)

📂 File Locations¶

03_06_07_services_stack/
├── services/
│   └── mkdocs/
│       ├── Dockerfile                          # ✅ Prepared (script disabled)
│       └── scripts/
│           └── discover_hierarchy.py           # ✅ Corrected script
└── HIERARCHY_DISCOVERY_INTEGRATION.md          # ← This file

🚀 How to Enable (When Ready)¶

Step 1: Uncomment Script in Dockerfile¶

Edit services/mkdocs/Dockerfile:

# Copy hierarchy discovery script
# NOTE: Currently DISABLED - uncomment when ready to enable auto-discovery
COPY --chown=audiodev:audiodev scripts/discover_hierarchy.py /opt/scripts/
RUN chmod +x /opt/scripts/discover_hierarchy.py

Change to:

# Copy hierarchy discovery script
COPY --chown=audiodev:audiodev scripts/discover_hierarchy.py /opt/scripts/
RUN chmod +x /opt/scripts/discover_hierarchy.py

Step 2: Update docker-compose.yml Command¶

Edit docker-compose.yml MkDocs service:

mkdocs:
  # ... other config ...
  command: mkdocs serve --dev-addr=0.0.0.0:8000

Change to:

mkdocs:
  # ... other config ...
  command: >
    sh -c "
    python /opt/scripts/discover_hierarchy.py &&
    mkdocs serve --dev-addr=0.0.0.0:8000 --watch-theme
    "

Step 3: Rebuild and Restart¶

# Rebuild MkDocs image
docker-compose build mkdocs

# Restart service
docker-compose up -d mkdocs

# View logs to verify
docker-compose logs -f mkdocs

📊 How It Works¶

Container Environment¶

Host Filesystem              Container Filesystem
─────────────────            ────────────────────
/path/to/audio-lab/          (not directly accessible)
├── 2 - FOUNDATION/
├── 06_BRAIN/
└── 07_META/
    └── 03_documentation/    →  /docs  (volume mount)
        ├── mkdocs.yml
        ├── docs/
        └── (generated)
            └── nav_structure.yml

Script Execution Flow¶

Script starts inside container at /opt/scripts/discover_hierarchy.py
Path detection:
Detects /docs mount point exists
Calculates repo root as /docs/../.. (via volume mount structure)
Hierarchy scan:
Scans repo root for XX_YY_ZZ_Name directories
Finds README files in each component
Navigation generation:
Creates hierarchical nav structure
Writes to /docs/nav_structure.yml
Updates /docs/mkdocs.yml
MkDocs starts:
Loads generated navigation
Serves documentation with auto-discovered structure

🧪 Testing the Script¶

Test in Isolation (Before Enabling)¶

# Access running mkdocs container
docker exec -it audiolab_mkdocs bash

# If script was copied (after uncommenting), run manually:
python /opt/scripts/discover_hierarchy.py

# Expected output:
# ======================================================================
# AudioLab Documentation Hierarchy Discovery
# ======================================================================
#
# 📍 Script location: /opt/scripts/discover_hierarchy.py
# ✓ Detected container environment
#   /docs mount → /docs
#   Repo root   → /docs/../..
# 📍 Repository root: /docs/../..
# 📍 Nav output: /docs/nav_structure.yml
# 📍 MkDocs config: /docs/mkdocs.yml
# ...

Verify Output Files¶

# Check generated nav structure
docker exec audiolab_mkdocs cat /docs/nav_structure.yml

# Check updated mkdocs config
docker exec audiolab_mkdocs cat /docs/mkdocs.yml

⚠️ Troubleshooting¶

Issue: Script Not Found¶

Error: /opt/scripts/discover_hierarchy.py: No such file or directory

Solution: You forgot to uncomment the COPY command in Dockerfile. See Step 1 above.

Issue: IndexError or Path Issues¶

Error: IndexError: tuple index out of range or similar path errors

Solution: The corrected script handles this. If still occurring:

Check volume mounts are correct in docker-compose.yml:

volumes:
  - ../../../../07_META/03_documentation:/docs:rw

Verify from inside container:

docker exec audiolab_mkdocs ls -la /docs
docker exec audiolab_mkdocs python -c "from pathlib import Path; print(Path('/docs').exists())"

Issue: No Hierarchy Found¶

Error: ⚠ No XX_YY_ZZ hierarchy found!

Possible causes: 1. Repository structure doesn't have XX_YY_ZZ directories 2. Volume mount is incorrect 3. Script is scanning wrong path

Debug:

# Check repo root detection
docker exec audiolab_mkdocs python -c "
from pathlib import Path
from scripts.discover_hierarchy import find_repo_root
print(find_repo_root(Path('/opt/scripts')))
"

# Manually check for XX_YY_ZZ directories
docker exec audiolab_mkdocs find /docs/../.. -type d -name "[0-9][0-9]_[0-9][0-9]_[0-9][0-9]_*" | head

Issue: Permission Denied Writing Files¶

Error: Permission denied: '/docs/nav_structure.yml'

Solution: Ensure volume mount has write permissions (:rw flag):

volumes:
  - ../../../../07_META/03_documentation:/docs:rw  # ← Note :rw

📝 Generated Output Format¶

nav_structure.yml¶

nav:
  - Level 02:
      - Level 04:
          - Core Interfaces: 2_foundation/04_core/04_01_core_interfaces/README.md
          - Math Primitives: 2_foundation/04_core/04_02_math_primitives/README.md
      - Level 05:
          - Buffer Management: 2_foundation/04_core/04_05_buffer_management/README.md

metadata:
  generated_by: discover_hierarchy.py
  description: Auto-generated navigation from XX_YY_ZZ hierarchy

Updated mkdocs.yml¶

The script merges the generated nav structure into mkdocs.yml and adds a reference:

# ... existing config ...

GENERATED_NAV_FILE: /docs/nav_structure.yml

nav:
  - Level 02:
      - Level 04:
          # ... auto-generated structure ...

🔄 Re-generation¶

Automatic Re-generation¶

The script runs every time the container starts (when enabled in docker-compose.yml).

To force re-generation:

docker-compose restart mkdocs

Manual Re-generation¶

# Run script manually
docker exec audiolab_mkdocs python /opt/scripts/discover_hierarchy.py

# Reload MkDocs (if using dev server, it auto-reloads)

📚 Integration Workflow¶

Development Workflow¶

Create new XX_YY_ZZ component:

mkdir "2 - FOUNDATION/04_CORE/04_XX_new_component"
echo "# New Component" > "2 - FOUNDATION/04_CORE/04_XX_new_component/README.md"

Restart MkDocs:
```
docker-compose restart mkdocs
```
Verify in docs:
Visit http://localhost:8000
New component appears in navigation automatically

CI/CD Integration¶

# Example GitHub Actions workflow
- name: Generate Documentation Nav
  run: |
    docker-compose run --rm mkdocs python /opt/scripts/discover_hierarchy.py

- name: Build Documentation
  run: |
    docker-compose run --rm mkdocs mkdocs build

🎯 Benefits of Auto-Discovery¶

✅ Automatic navigation: No manual mkdocs.yml editing for new components

✅ Consistency: Navigation structure matches repository structure

✅ Developer-friendly: Add README.md to component → automatically in docs

✅ Hierarchy enforcement: Only XX_YY_ZZ directories included

✅ Maintenance-free: Documentation scales with codebase

🔐 Security Considerations¶

Current setup is safe: - ✅ Script runs as non-root user (audiodev:1000) - ✅ Only writes to /docs (mounted volume) - ✅ Read-only scan of repository structure - ✅ No external network access required

Production recommendations: - Pin Python package versions (already done in Dockerfile) - Validate YAML output before merging to mkdocs.yml - Run in isolated container (already isolated)

📅 Roadmap¶

Current Status (v1.0)¶

✅ Basic XX_YY_ZZ pattern detection
✅ README.md file discovery
✅ MkDocs nav generation
✅ Container-optimized paths

Future Enhancements (v2.0)¶

Support for index.md files
Metadata extraction from frontmatter
Diagram file detection and linking
Component dependency visualization
Search integration with hierarchy

Future Enhancements (v3.0)¶

Real-time file watching (regenerate on changes)
Multi-language documentation support
Custom hierarchy patterns beyond XX_YY_ZZ
GraphQL API for hierarchy data

🆘 Support¶

If you encounter issues:

Check this guide for troubleshooting section
View container logs:
```
docker-compose logs mkdocs
```

Test script manually:

docker exec -it audiolab_mkdocs python /opt/scripts/discover_hierarchy.py

Verify paths:

docker exec audiolab_mkdocs ls -la /docs /opt/scripts

Remember: The feature is currently DISABLED by default. Enable only when ready and tested.

Last Updated: 2025-10-04 Status: Ready for activation when needed Script Version: 2.0 (Container-Optimized)