Feat/auto docs

.gemini/config.yaml

@@ -0,0 +1,13 @@
+have_fun: false
+memory_config:
+  disabled: false
+code_review:
+  disable: false
+  comment_severity_threshold: MEDIUM
+  max_review_comments: -1
+  pull_request_opened:
+    help: false
+    summary: true
+    code_review: true
+    include_drafts: true
+ignore_patterns: []

.gemini/styleguide.md

@@ -0,0 +1,28 @@
+# Gemini Code Assist PR Review Styleguide
+**Repository:** `RatioPath` (RationAI)
+**Context:** This is a Python library for large-scale processing, analysis, and transformation of whole-slide pathology images (WSIs).
+It is built on top of the Ray framework to enable distributed, fault-tolerant, and scalable pipelines across multi-node environments.
+
+## 📝 General Comment Style
+- Keep comments **short and actionable**.
+- Prefer **bullet points** over long paragraphs.
+- Point to specific lines or sections when possible.
+- Suggest improvements, not rewrite entire snippets.
+- Avoid repetition of what the code already clearly states.
+- Defer to the repo’s existing conventions unless there’s a clear bug or inconsistency.
+
+## 📚 Documentation Review Expectations
+- Highlight missing or incomplete documentation whenever a PR introduces new public API surface.
+- Treat new public modules, classes, functions, methods, CLI entry points, configuration options, and user-facing behaviors as documentation candidates.
+- Flag missing Google-style docstrings for new public Python objects when they should be part of the library API.
+- Flag missing user or reference documentation when a change adds new functionality that users need to discover or understand.
+- Check that documentation examples use the real package import paths exposed by `ratiopath`.
+- Mention when docstrings are too thin for rendered API docs and should include sections like `Args:`, `Returns:`, `Yields:`, `Raises:`, or `Examples:` when relevant.
+- If a PR changes behavior, configuration, or usage without updating docs, leave a review comment asking for the missing documentation.
+
+## ✅ Documentation Review Triggers
+- New public function, class, or module added without docstrings.
+- New feature added without corresponding user-facing docs or reference docs.
+- New parameter, return behavior, exception behavior, or example-worthy workflow added without documentation updates.
+- Renamed or relocated public API without documentation and examples being updated.
+- Changes that affect MkDocs or generated API reference output without matching documentation changes.

.github/workflows/docs-preview.yml

@@ -0,0 +1,118 @@
+name: Documentation Preview
+
+on:
+  pull_request:
+    branches: ["main"]
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "docs/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-preview-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build preview
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install documentation dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation site
+        run: uv run mkdocs build --strict
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload documentation artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    name: Deploy preview
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    outputs:
+      page_url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy GitHub Pages preview
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          preview: true
+
+  comment:
+    name: Comment preview link
+    runs-on: ubuntu-latest
+    needs: deploy
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Add or update PR comment
+        uses: actions/github-script@v8
+        env:
+          PAGE_URL: ${{ needs.deploy.outputs.page_url }}
+        with:
+          script: |
+            const marker = '<!-- docs-preview-comment -->';
+            const body = [
+              marker,
+              '## Documentation Preview',
+              '',
+              `Preview URL: ${process.env.PAGE_URL}`,
+            ].join('\n');
+
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner,
+              repo,
+              issue_number,
+            });
+
+            const existingComment = comments.find(
+              (comment) => comment.user?.type === 'Bot' && comment.body?.includes(marker),
+            );
+
+            if (existingComment) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existingComment.id,
+                body,
+              });
+              return;
+            }
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number,
+              body,
+            });