diff --git a/.github/workflows/csharp.yml b/.github/workflows/csharp.yml index 6ceac78..2a9318c 100644 --- a/.github/workflows/csharp.yml +++ b/.github/workflows/csharp.yml @@ -162,8 +162,34 @@ jobs: - name: Publish documentation to gh-pages branch run: | export REPOSITORY_NAME=$(basename ${{ github.repository }}) - wget "$SCRIPTS_BASE_URL/docfx.json" + + # Download filter.yml 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 custom docfx.json and toc.yml with PDF support from repository + cp ../docfx.json ./docfx.json + cp ../toc.yml ./toc.yml + cp ../publish-docs-with-pdf.sh ./publish-docs-with-pdf.sh + chmod +x ./publish-docs-with-pdf.sh + + # Install modern DocFX with PDF support + dotnet tool install -g docfx --version 2.78.3 + + # Replace repository name in configurations + sed -i "s/\$REPOSITORY_NAME/$REPOSITORY_NAME/g" docfx.json + sed -i "s/\$REPOSITORY_NAME/$REPOSITORY_NAME/g" toc.yml + + # Generate HTML documentation + docfx docfx.json + + # Generate PDF documentation + docfx pdf docfx.json + + # Copy PDF to site directory + mkdir -p _site + if [ -d "_site_pdf" ] && [ "$(ls -A _site_pdf)" ]; then + cp _site_pdf/*.pdf _site/ 2>/dev/null || echo "No PDF files generated" + fi + + # Publish documentation with PDF + bash ./publish-docs-with-pdf.sh diff --git a/docfx.json b/docfx.json new file mode 100644 index 0000000..4240f60 --- /dev/null +++ b/docfx.json @@ -0,0 +1,63 @@ +{ + "metadata": [ + { + "src": [ + { + "files": [ "**/*.sln" ], + "exclude": [ "**/bin/**", "**/obj/**" ], + "src": "" + } + ], + "dest": "obj/api", + "filter": "filter.yml", + "properties": { "TargetFramework": "netstandard2.0" } + } + ], + "build": { + "content": [ + { + "files": [ "**/*.yml" ], + "src": "obj/api", + "dest": "api" + }, + { + "files": [ "*.md", "toc.yml" ] + } + ], + "globalMetadata": { + "_appTitle": "LinksPlatform's Platform.$REPOSITORY_NAME Library", + "_enableSearch": true, + "_gitContribute": { + "branch": "master" + }, + "_gitUrlPattern": "github", + "pdf": true, + "pdfFileName": "Platform.$REPOSITORY_NAME.pdf", + "pdfTocPage": true, + "pdfCoverPage": true + }, + "markdownEngineName": "markdig", + "dest": "_site", + "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ] + }, + "pdf": { + "content": [ + { + "files": [ "**/*.yml" ], + "src": "obj/api", + "dest": "api" + }, + { + "files": [ "*.md", "toc.yml" ] + } + ], + "dest": "_site_pdf", + "globalMetadata": { + "_appTitle": "LinksPlatform's Platform.$REPOSITORY_NAME Library", + "pdf": true, + "pdfFileName": "Platform.$REPOSITORY_NAME.pdf", + "pdfTocPage": true, + "pdfCoverPage": true + } + } +} diff --git a/publish-docs-with-pdf.sh b/publish-docs-with-pdf.sh new file mode 100644 index 0000000..559a42f --- /dev/null +++ b/publish-docs-with-pdf.sh @@ -0,0 +1,52 @@ +#!/bin/bash +set -e # Exit with nonzero exit code if anything fails + +# Settings +TARGET_BRANCH="gh-pages" +SHA=$(git rev-parse --verify HEAD) +COMMIT_USER_NAME="linksplatform" +COMMIT_USER_EMAIL="linksplatformtechnologies@gmail.com" +REPOSITORY="github.com/linksplatform/$REPOSITORY_NAME" + +# Clone the existing gh-pages for this repo into out/ +# Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deploy) +git clone "https://$REPOSITORY" out +cd out || exit +git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH +cd .. + +mkdir -p out/csharp + +# Clean out existing contents +rm -rf out/csharp/**/* || exit 0 + +# Copy generated docs site (includes PDF files) +cp -r _site/* out/csharp/ + +cd out/csharp || exit + +# Do not use index.md +cp README.html index.html + +# Enter repository's folder +cd .. + +# Now let's go have some fun with the cloned repo +git config user.name "$COMMIT_USER_NAME" +git config user.email "$COMMIT_USER_EMAIL" +git remote rm origin +git remote add origin "https://linksplatform:$GITHUB_TOKEN@$REPOSITORY.git" + +# Commit the "changes", i.e. the new version. +# The delta will show diffs between new and old versions. +git add --all +git commit -m "Deploy to GitHub Pages with PDF documentation: $SHA" + +# Now that we're all set up, we can push. +git push "https://linksplatform:$GITHUB_TOKEN@$REPOSITORY.git" "$TARGET_BRANCH" +cd .. + +# Clean up +rm -rf out +rm -rf _site +rm -rf _site_pdf \ No newline at end of file diff --git a/toc.yml b/toc.yml new file mode 100644 index 0000000..1fa0a23 --- /dev/null +++ b/toc.yml @@ -0,0 +1,7 @@ +pdf: true +items: +- name: Home + href: README.md +- name: API Documentation + href: obj/api/ + homepage: api/Platform.$REPOSITORY_NAME.html