Configure DocFX to generate PDF with documentation

.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

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
+    }
+  }
+}

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

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