fix(webapp): קישורי תפריט פנימיים במסמכי Markdown לא גללו לסעיף (#3201) #5696
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: 📖 Build and Deploy Documentation | |
| on: | |
| push: | |
| branches: [main, develop] | |
| paths: | |
| - '**.py' | |
| - 'docs/**' | |
| - 'requirements/*.txt' | |
| - '.github/workflows/documentation.yml' | |
| pull_request: | |
| branches: [main] | |
| paths: | |
| - '**.py' | |
| - 'docs/**' | |
| schedule: | |
| - cron: '0 2 * * *' | |
| release: | |
| types: [published] | |
| workflow_dispatch: | |
| inputs: | |
| deploy: | |
| description: 'Deploy to GitHub Pages' | |
| required: false | |
| default: 'false' | |
| type: choice | |
| options: | |
| - 'true' | |
| - 'false' | |
| env: | |
| PYTHON_VERSION: '3.11' | |
| SPHINX_BUILD_DIR: docs/_build/html | |
| concurrency: | |
| group: docs-${{ github.event.pull_request.number || github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| build-docs: | |
| name: 🔨 Build Documentation | |
| if: ${{ github.event_name != 'schedule' && !(github.event_name == 'pull_request' && github.event.pull_request.draft) }} | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: read | |
| issues: write | |
| pull-requests: write | |
| steps: | |
| - name: 📥 Checkout code | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: ${{ github.event_name == 'pull_request' && 1 || 0 }} | |
| - name: 🐍 Setup Python ${{ env.PYTHON_VERSION }} | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: ${{ env.PYTHON_VERSION }} | |
| cache: 'pip' | |
| cache-dependency-path: | | |
| requirements/*.txt | |
| docs/requirements.txt | |
| - name: 📦 Install documentation dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| # Install only docs dependencies (conf.py mocks heavy imports) | |
| pip install -r docs/requirements.txt | |
| - name: 🔍 Check documentation style | |
| continue-on-error: true | |
| run: | | |
| pip install pydocstyle | |
| pydocstyle --count --convention=google --add-ignore=D100,D104 || true | |
| - name: Cache Sphinx doctrees | |
| uses: actions/cache@v4 | |
| with: | |
| path: docs/_build/doctrees | |
| key: docs-doctrees-${{ github.ref }}-${{ hashFiles('docs/**/*.rst', 'docs/conf.py') }} | |
| restore-keys: | | |
| docs-doctrees-${{ github.ref }}- | |
| docs-doctrees- | |
| - name: 🔨 Build docs (PR single-version) | |
| if: github.event_name == 'pull_request' | |
| run: | | |
| cd docs | |
| DISABLE_DB=1 python -m sphinx -b html . _build/html --keep-going -j auto | |
| env: | |
| SPHINX_MOCK_IMPORTS: true | |
| BOT_TOKEN: dummy_token_for_docs | |
| MONGODB_URL: mongodb://localhost:27017/test | |
| - name: 🔨 Build docs (single-version for stability) | |
| if: github.ref == 'refs/heads/main' && github.event_name == 'push' | |
| run: | | |
| cd docs | |
| DISABLE_DB=1 python -m sphinx -b html . _build/html --keep-going -j auto | |
| - name: 📊 Generate documentation coverage report | |
| if: github.event_name == 'pull_request' | |
| continue-on-error: true | |
| run: | | |
| cd docs | |
| python -m sphinx -b coverage . _build/coverage | |
| echo "### 📊 Documentation Coverage Report" >> $GITHUB_STEP_SUMMARY | |
| echo '```' >> $GITHUB_STEP_SUMMARY | |
| cat _build/coverage/python.txt >> $GITHUB_STEP_SUMMARY || echo "No coverage data available" >> $GITHUB_STEP_SUMMARY | |
| echo '```' >> $GITHUB_STEP_SUMMARY | |
| - name: 💾 Upload documentation artifacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: documentation-html | |
| path: ${{ env.SPHINX_BUILD_DIR }} | |
| retention-days: 7 | |
| - name: 📝 Generate documentation info | |
| run: | | |
| echo "### 📖 Documentation Build Info" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Branch**: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Commit**: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Python**: ${{ env.PYTHON_VERSION }}" >> $GITHUB_STEP_SUMMARY | |
| SPHINX_VER=$(python -c 'import sphinx; print("Sphinx " + sphinx.__version__)') | |
| echo "- **Sphinx**: ${SPHINX_VER}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Build Time**: $(date -u +"%Y-%m-%d %H:%M:%S UTC")" >> $GITHUB_STEP_SUMMARY | |
| # Count documentation files | |
| echo "- **HTML Files**: $(find ${{ env.SPHINX_BUILD_DIR }} -name "*.html" | wc -l)" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Total Size**: $(du -sh ${{ env.SPHINX_BUILD_DIR }} | cut -f1)" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "✅ **Documentation built successfully!**" >> $GITHUB_STEP_SUMMARY | |
| echo "" >> $GITHUB_STEP_SUMMARY | |
| echo "⚠️ Note: Some warnings may appear during build. This is normal for projects with external dependencies." >> $GITHUB_STEP_SUMMARY | |
| - name: 💬 Comment on PR with preview link | |
| if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository | |
| continue-on-error: true | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const artifactUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; | |
| const comments = await github.rest.issues.listComments({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: context.issue.number, | |
| }); | |
| const botComment = comments.data.find(comment => | |
| comment.user.type === 'Bot' && comment.body.includes('📖 Documentation Preview') | |
| ); | |
| const body = `## 📖 Documentation Preview | |
| The documentation has been built successfully! | |
| - 📦 [Download Documentation Artifacts](${artifactUrl}) | |
| - 🔍 Check the workflow summary for coverage report | |
| - 📊 Build completed at: ${new Date().toUTCString()} | |
| To view locally: | |
| 1. Download the artifacts | |
| 2. Extract the zip file | |
| 3. Open \`index.html\` in your browser`; | |
| if (botComment) { | |
| await github.rest.issues.updateComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| comment_id: botComment.id, | |
| body: body | |
| }); | |
| } else { | |
| await github.rest.issues.createComment({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| issue_number: context.issue.number, | |
| body: body | |
| }); | |
| } | |
| deploy-docs: | |
| name: 🚀 Deploy to GitHub Pages | |
| needs: build-docs | |
| if: | | |
| (github.ref == 'refs/heads/main' && github.event_name == 'push') || | |
| (github.event_name == 'release') || | |
| (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true') | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: 📥 Download documentation artifact | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: documentation-html | |
| path: public | |
| - name: ✅ Verify public directory | |
| run: | | |
| if [ ! -d "public" ]; then | |
| echo "Directory ./public does not exist (artifact missing)." | |
| exit 1 | |
| fi | |
| - name: 📄 Setup GitHub Pages | |
| uses: actions/configure-pages@v4 | |
| # שם artifact ייחודי לכל ניסיון ריצה: ב-Re-run ה-artifact מהניסיון הקודם | |
| # נשאר משויך לאותו run, ושני artifacts בשם "github-pages" מפילים את | |
| # deploy-pages@v4 ("Multiple artifacts named github-pages"). run_attempt | |
| # מבטיח שם חדש בכל ניסיון, ו-deploy-pages מקבל את אותו שם במפורש. | |
| - name: 📦 Upload to GitHub Pages | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: ./public | |
| name: github-pages-${{ github.run_attempt }} | |
| - name: 🚀 Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| with: | |
| artifact_name: github-pages-${{ github.run_attempt }} | |
| - name: ✅ Deployment summary | |
| run: | | |
| echo "### 🚀 Documentation Deployed!" >> $GITHUB_STEP_SUMMARY | |
| echo "- **URL**: ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Environment**: github-pages" >> $GITHUB_STEP_SUMMARY | |
| echo "- **Deployed at**: $(date -u +"%Y-%m-%d %H:%M:%S UTC")" >> $GITHUB_STEP_SUMMARY | |
| linkcheck-nightly: | |
| name: 🔗 Nightly linkcheck (Sphinx) | |
| if: ${{ github.event_name == 'schedule' }} | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: 📥 Checkout code | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 1 | |
| - name: 🐍 Setup Python ${{ env.PYTHON_VERSION }} | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: ${{ env.PYTHON_VERSION }} | |
| cache: 'pip' | |
| cache-dependency-path: | | |
| docs/requirements.txt | |
| - name: 📦 Install docs deps | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install -r docs/requirements.txt | |
| - name: 🔗 Run linkcheck | |
| continue-on-error: true | |
| run: | | |
| cd docs | |
| python -m sphinx -b linkcheck . _build/linkcheck || true | |
| if [ -f "_build/linkcheck/output.txt" ]; then | |
| echo "### 🔗 Link Check Report (Nightly)" >> $GITHUB_STEP_SUMMARY | |
| echo '```' >> $GITHUB_STEP_SUMMARY | |
| head -100 _build/linkcheck/output.txt >> $GITHUB_STEP_SUMMARY | |
| echo '```' >> $GITHUB_STEP_SUMMARY | |
| fi | |
| notify-failure: | |
| name: 📢 Notify on Failure | |
| needs: [build-docs] | |
| if: failure() | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: 📢 Create issue for documentation failure | |
| if: github.ref == 'refs/heads/main' | |
| uses: actions/github-script@v7 | |
| with: | |
| script: | | |
| const title = `📖 Documentation Build Failed - ${new Date().toISOString().split('T')[0]}`; | |
| const body = `## ❌ Documentation Build Failed | |
| The documentation build failed on the main branch. | |
| **Details:** | |
| - Commit: ${context.sha} | |
| - Workflow: [${context.workflow}](https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) | |
| - Time: ${new Date().toUTCString()} | |
| Please check the workflow logs and fix the documentation build.`; | |
| await github.rest.issues.create({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| title: title, | |
| body: body, | |
| labels: ['documentation', 'bug', 'automated'] | |
| }); |