docs.yml

name: Documentation

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.11"

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install markdown-it-py[linkify,plugins] linkchecker

    - name: Validate Markdown syntax
      run: |
        python -c "
        import markdown_it
        import sys
        from pathlib import Path
        
        md = markdown_it.MarkdownIt()
        errors = []
        
        for md_file in Path('.').glob('*.md'):
            try:
                with open(md_file, 'r', encoding='utf-8') as f:
                    content = f.read()
                md.parse(content)
                print(f'✅ {md_file} - Valid Markdown')
            except Exception as e:
                errors.append(f'❌ {md_file} - {e}')
                print(f'❌ {md_file} - {e}')
        
        if errors:
            print(f'\nFound {len(errors)} Markdown errors')
            sys.exit(1)
        else:
            print(f'\n✅ All Markdown files are valid')
        "

    - name: Check documentation completeness
      run: |
        python -c "
        import sys
        from pathlib import Path
        
        required_files = [
            'README.md',
            'LICENSE', 
            'CHANGELOG.md',
            'CONTRIBUTING.md',
            'SECURITY.md'
        ]
        
        missing = []
        for file in required_files:
            if not Path(file).exists():
                missing.append(file)
        
        if missing:
            print(f'❌ Missing required documentation files: {missing}')
            sys.exit(1)
        else:
            print('✅ All required documentation files present')
        "

    - name: Validate links in documentation
      run: |
        # Check for broken internal links in README
        python -c "
        import re
        from pathlib import Path
        
        readme_content = Path('README.md').read_text()
        
        # Find internal file links
        internal_links = re.findall(r'\[.*?\]\(([^http][^)]+)\)', readme_content)
        
        broken_links = []
        for link in internal_links:
            # Remove anchors
            file_path = link.split('#')[0]
            if file_path and not Path(file_path).exists():
                broken_links.append(link)
        
        if broken_links:
            print(f'❌ Broken internal links found: {broken_links}')
            exit(1)
        else:
            print('✅ All internal links are valid')
        "

    - name: Check code examples in README
      run: |
        python -c "
        import re
        from pathlib import Path
        
        readme_content = Path('README.md').read_text()
        
        # Find Python code blocks
        python_blocks = re.findall(r'```python\n(.*?)\n```', readme_content, re.DOTALL)
        bash_blocks = re.findall(r'```bash\n(.*?)\n```', readme_content, re.DOTALL)
        
        print(f'Found {len(python_blocks)} Python code examples')
        print(f'Found {len(bash_blocks)} Bash code examples')
        
        # Basic validation - check for common issues
        issues = []
        for i, block in enumerate(python_blocks):
            if 'import' in block and 'moondream_mcp' in block:
                if 'from moondream_mcp' not in block and 'import moondream_mcp' not in block:
                    issues.append(f'Python block {i+1}: Possible import issue')
        
        if issues:
            print(f'⚠️  Potential issues in code examples: {issues}')
        else:
            print('✅ Code examples look good')
        "

  check-pyproject:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.11"

    - name: Validate pyproject.toml
      run: |
        python -c "
        import tomllib
        from pathlib import Path
        
        try:
            with open('pyproject.toml', 'rb') as f:
                config = tomllib.load(f)
            
            # Check required fields
            project = config.get('project', {})
            required_fields = ['name', 'version', 'description', 'authors', 'license']
            
            missing = [field for field in required_fields if field not in project]
            if missing:
                print(f'❌ Missing required fields in pyproject.toml: {missing}')
                exit(1)
            
            print('✅ pyproject.toml is valid and complete')
            
        except Exception as e:
            print(f'❌ Error parsing pyproject.toml: {e}')
            exit(1)
        "

  validate-examples:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.11"

    - name: Check examples directory
      run: |
        python -c "
        import sys
        from pathlib import Path
        
        examples_dir = Path('examples')
        if not examples_dir.exists():
            print('⚠️  No examples directory found')
            sys.exit(0)
        
        # Check for required example files
        required_examples = [
            'README.md',
            'requirements.txt',
            'QUICKSTART.md'
        ]
        
        missing = []
        for file in required_examples:
            if not (examples_dir / file).exists():
                missing.append(file)
        
        if missing:
            print(f'❌ Missing example files: {missing}')
            sys.exit(1)
        else:
            print('✅ All required example files present')
        "

    - name: Validate example requirements
      run: |
        if [ -f examples/requirements.txt ]; then
          python -c "
from pathlib import Path

requirements = Path('examples/requirements.txt').read_text()
lines = [line.strip() for line in requirements.split('\n') if line.strip() and not line.startswith('#')]

print(f'Found {len(lines)} requirements in examples/requirements.txt')

# Check for common issues
issues = []
for line in lines:
    if '==' not in line and '>=' not in line and '~=' not in line:
        issues.append(f'No version specified for: {line}')

if issues:
    print(f'⚠️  Potential issues: {issues}')
else:
    print('✅ Requirements file looks good')
          "
        else
          echo "⚠️  No examples/requirements.txt found"
        fi