first commit of docs

Author: phborba

.github/workflows/docs.yml

@@ -0,0 +1,123 @@
+name: Deploy Documentation
+
+on:
+  # Trigger on push to main branch
+  push:
+    branches: [main, master]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'pytorch_segmentation_models_trainer/**/*.py'  # Rebuild on code changes for API docs
+      - '.github/workflows/docs.yml'
+  
+  # Allow manual triggering
+  workflow_dispatch:
+  
+  # Trigger on pull requests for testing (but don't deploy)
+  pull_request:
+    branches: [main, master]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+# Set permissions for GitHub Pages deployment
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build documentation
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch full history for git info
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter
+          # Install your package for API documentation
+          pip install -e .
+
+      - name: Configure Git for mkdocs
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload documentation artifacts
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./site
+
+  # Deploy to GitHub Pages (only on main branch)
+  deploy:
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
+    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@v2
+
+  # Test documentation build on PRs (without deploying)
+  test:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter
+          pip install -e .
+
+      - name: Test documentation build
+        run: mkdocs build --strict
+
+      - name: Test internal links
+        run: |
+          # Install link checker
+          pip install mkdocs-linkcheck
+          # Check for broken internal links
+          mkdocs build --strict --site-dir test_site
+          
+      - name: Comment PR with preview info
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '📚 Documentation build successful! The changes look good and ready to be deployed.'
+            })

docs/README.md

@@ -0,0 +1,157 @@
+# Documentation
+
+This folder contains the documentation for PyTorch Segmentation Models Trainer.
+
+## Building Documentation
+
+### Prerequisites
+
+```bash
+pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-jupyter
+```
+
+### Local Development
+
+```bash
+# Serve documentation locally with auto-reload
+mkdocs serve
+
+# Open http://127.0.0.1:8000 in your browser
+```
+
+### Building Static Site
+
+```bash
+# Build static HTML files
+mkdocs build
+
+# Output will be in site/ directory
+```
+
+## Deployment
+
+### GitHub Pages
+
+```bash
+# Deploy to GitHub Pages (requires push access)
+mkdocs gh-deploy
+```
+
+### Manual Deployment
+
+1. Build the documentation:
+   ```bash
+   mkdocs build
+   ```
+
+2. Copy the `site/` folder contents to your web server.
+
+## Writing Documentation
+
+### File Structure
+
+- `docs/` - All documentation files
+- `mkdocs.yml` - Configuration file
+- Use `.md` files for content
+- Follow the navigation structure in `mkdocs.yml`
+
+### Writing Guidelines
+
+1. **Use descriptive headings** with proper hierarchy
+2. **Include code examples** with syntax highlighting
+3. **Add tips and warnings** using admonitions:
+   ```markdown
+   !!! tip "Pro Tip"
+       This is a helpful tip
+   
+   !!! warning "Important"
+       This is a warning
+   ```
+
+4. **Cross-reference** other pages:
+   ```markdown
+   See the [Installation Guide](getting-started/installation.md)
+   ```
+
+5. **API Documentation** using mkdocstrings:
+   ```markdown
+   ::: pytorch_segmentation_models_trainer.main
+       options:
+         show_source: true
+   ```
+
+### Adding New Pages
+
+1. Create the markdown file in appropriate directory
+2. Add to navigation in `mkdocs.yml`:
+   ```yaml
+   nav:
+     - New Section:
+       - New Page: path/to/new-page.md
+   ```
+
+## Auto-generated Content
+
+Some content is automatically generated:
+
+- **API Reference**: From docstrings using mkdocstrings
+- **Navigation**: From `mkdocs.yml` structure
+- **Search Index**: Automatically built by MkDocs
+
+## Customization
+
+### Theme Customization
+
+Edit `mkdocs.yml`:
+
+```yaml
+theme:
+  name: material
+  palette:
+    primary: blue
+    accent: blue
+  features:
+    - navigation.tabs
+    - search.highlight
+```
+
+### Adding Extensions
+
+Add to `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - pymdownx.superfences
+  - admonition
+  - tables
+```
+
+## Contributing
+
+1. Write clear, concise documentation
+2. Include working examples
+3. Test all code snippets  
+4. Check links work correctly
+5. Preview locally before submitting
+
+## Troubleshooting
+
+### Common Issues
+
+**Missing dependencies**:
+```bash
+pip install mkdocs-material mkdocstrings[python]
+```
+
+**API docs not generating**:
+- Check docstrings exist in Python files
+- Verify module paths in `::: module.name` references
+
+**Build errors**:
+- Check YAML syntax in `mkdocs.yml`
+- Verify all referenced files exist
+- Check markdown syntax
+
+**Broken links**:
+- Use relative paths: `[link](../other-page.md)`
+- Check file extensions match exactly