Skip to content

Move PDF generation to dedicated VM and unify documentation publishing #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
konard wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Move PDF generation to dedicated VM and unify documentation publishing #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fd92084
Initial commit with task details for issue #59
konard Sep 10, 2025
14a7c28
Remove CLAUDE.md - PR created successfully
konard Sep 10, 2025
bdbea31
Move PDF generation to dedicated VM and unify documentation publishing
konard Sep 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 21 additions & 9 deletions .github/workflows/csharp.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ jobs:
echo "::set-output name=isCsFilesChanged::${isCsFilesChanged}"
echo "isCsFilesChanged: ${isCsFilesChanged}"
generatePdfWithCode:
runs-on: ubuntu-latest
runs-on: [self-hosted, pdf-generation]
needs: [findChangedCsFiles]
if: ${{ needs.findChangedCsFiles.outputs.isCsFilesChanged == 'true' }}
steps:
Expand All @@ -139,16 +139,22 @@ jobs:
- uses: actions/checkout@v1
with:
submodules: true
- name: Generate PDF with code
- name: Generate PDF with code (optimized for dedicated VM)
run: |
export REPOSITORY_NAME=$(basename ${{ github.repository }})
wget "$SCRIPTS_BASE_URL/format-csharp-files.py"
wget "$SCRIPTS_BASE_URL/format-csharp-document.sh"
wget "$SCRIPTS_BASE_URL/generate-csharp-pdf.sh"
bash ./generate-csharp-pdf.sh
- name: Upload PDF artifact for documentation publishing
uses: actions/upload-artifact@v3
with:
name: generated-pdf
path: _site/Platform.${{ github.event.repository.name }}.pdf
retention-days: 1
publishDocumentation:
runs-on: ubuntu-latest
needs: [findChangedCsFiles]
needs: [findChangedCsFiles, generatePdfWithCode]
if: ${{ needs.findChangedCsFiles.outputs.isCsFilesChanged == 'true' }}
steps:
- name: Setup .NET
Expand All @@ -159,11 +165,17 @@ jobs:
- uses: actions/checkout@v1
with:
submodules: true
- name: Publish documentation to gh-pages branch
- name: Download PDF artifact
uses: actions/download-artifact@v3
with:
name: generated-pdf
path: _site/
- name: Publish unified documentation to gh-pages branch
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SCRIPTS_BASE_URL: https://raw.githubusercontent.com/linksplatform/Scripts/main/MultiProjectRepository
run: |
export REPOSITORY_NAME=$(basename ${{ github.repository }})
wget "$SCRIPTS_BASE_URL/docfx.json"
wget "$SCRIPTS_BASE_URL/filter.yml"
wget "$SCRIPTS_BASE_URL/toc.yml"
wget "$SCRIPTS_BASE_URL/publish-csharp-docs.sh"
bash ./publish-csharp-docs.sh
# Use local unified publishing script
chmod +x ./.scripts/publish-unified-docs.sh
bash ./.scripts/publish-unified-docs.sh
151 changes: 151 additions & 0 deletions .scripts/publish-unified-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
#!/bin/bash
set -e # Exit with nonzero exit code if anything fails

# Unified documentation publishing script
# This script combines documentation generation with PDF publishing
# Based on react-deep-tree approach and existing documentation scripts

export REPOSITORY_NAME=$(basename $(git remote get-url origin | sed 's/.*\///g' | sed 's/\.git//g'))

echo "Publishing unified documentation for repository: $REPOSITORY_NAME"

# Create output directory
mkdir -p _site

# Check if PDF was generated by dedicated VM and exists
if [ -f "_site/Platform.$REPOSITORY_NAME.pdf" ]; then
echo "✓ PDF artifact found from dedicated generation VM"
else
echo "⚠ No PDF artifact found - documentation will be published without PDF"
fi

# Generate API documentation using DocFX (if not already present)
if [ ! -d "_site/api" ]; then
echo "Generating API documentation..."

# Download DocFX configuration if not present
if [ ! -f "docfx.json" ]; then
wget -q "$SCRIPTS_BASE_URL/docfx.json" || echo "Using default docfx configuration"
fi

# Generate documentation
dotnet tool install -g docfx || echo "DocFX already installed"
export PATH="$PATH:$HOME/.dotnet/tools"
docfx metadata docfx.json --force || echo "Metadata generation completed with warnings"
docfx build docfx.json --force || echo "Documentation build completed"
fi

# Create unified index page that links to both API docs and PDF
cat > _site/index.html << EOF
<!DOCTYPE html>
<html>
<head>
<title>Platform.$REPOSITORY_NAME Documentation</title>
<meta charset="utf-8">
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
max-width: 800px;
margin: 2rem auto;
padding: 0 1rem;
line-height: 1.6;
}
.header { text-align: center; margin-bottom: 2rem; }
.section { margin: 2rem 0; }
.link-card {
display: block;
padding: 1rem;
margin: 1rem 0;
border: 1px solid #ddd;
border-radius: 8px;
text-decoration: none;
color: #333;
transition: box-shadow 0.2s;
}
.link-card:hover { box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
.link-title { font-weight: bold; font-size: 1.1em; }
.link-desc { color: #666; margin-top: 0.5rem; }
</style>
</head>
<body>
<div class="header">
<h1>Platform.$REPOSITORY_NAME</h1>
<p>Comprehensive documentation and API reference</p>
</div>

<div class="section">
<h2>Documentation</h2>

<a href="api/" class="link-card">
<div class="link-title">📖 API Documentation</div>
<div class="link-desc">Browse the complete API reference with detailed class and method documentation</div>
</a>

EOF

# Add PDF link only if PDF exists
if [ -f "_site/Platform.$REPOSITORY_NAME.pdf" ]; then
cat >> _site/index.html << EOF
<a href="Platform.$REPOSITORY_NAME.pdf" class="link-card">
<div class="link-title">📄 PDF Documentation</div>
<div class="link-desc">Download the complete source code documentation as a PDF file</div>
</a>
EOF
fi

cat >> _site/index.html << EOF
</div>

<div class="section">
<h2>Quick Links</h2>
<p>
<a href="https://github.com/linksplatform/$REPOSITORY_NAME">🔗 GitHub Repository</a> |
<a href="https://www.nuget.org/packages/Platform.$REPOSITORY_NAME">📦 NuGet Package</a>
</p>
</div>
</body>
</html>
EOF

echo "✓ Unified documentation index created"

# Deploy to GitHub Pages
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"

# Clone gh-pages branch or create it
if git ls-remote --exit-code --heads origin gh-pages; then
git clone --single-branch --branch gh-pages "https://x-access-token:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git" gh-pages
cd gh-pages
rm -rf *
else
mkdir gh-pages
cd gh-pages
git init
git remote add origin "https://x-access-token:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git"
git checkout -b gh-pages
fi

# Copy generated documentation
cp -r ../_site/* .

# Commit and push
git add .
if git diff --staged --quiet; then
echo "No changes to documentation"
else
git commit -m "📚 Update unified documentation

- API documentation generated via DocFX
- PDF documentation $([ -f "Platform.$REPOSITORY_NAME.pdf" ] && echo "included" || echo "not available")
- Unified landing page with quick navigation

🤖 Generated with GitHub Actions"
git push origin gh-pages
echo "✓ Documentation published to GitHub Pages"
fi

cd ..
rm -rf gh-pages

echo "🎉 Unified documentation publishing completed successfully"
Loading