ApiDocs with docfx (#44)

sanych-sun · Oleksandr Poliakov · web-flow · commit 1c6cfbc7fe8a · 2023-11-27T17:37:51.000Z
Co-authored-by: Oleksandr Poliakov &lt;oleksandr.poliakov@mongodb.com&gt;
diff --git a/.gitignore b/.gitignore
@@ -63,6 +63,7 @@ src/packages
 .dotnet
 
 # Other
+.config
 artifacts
 packages
 /tools
diff --git a/apidocs/.gitignore b/apidocs/.gitignore
@@ -0,0 +1,2 @@
+.manifest
+api/**.yml
diff --git a/apidocs/api/MongoDB.md b/apidocs/api/MongoDB.md
@@ -0,0 +1,3 @@
+﻿---
+redirect_url: ../index.html
+---
diff --git a/apidocs/api/index.md b/apidocs/api/index.md
diff --git a/apidocs/docfx.json b/apidocs/docfx.json
@@ -21,28 +21,28 @@
     "build": {
         "content": [
             {
-                "files": ["api/**.yml", "api/index.md"]
+                "files": ["api/**.yml", "api/index.md", "api/MongoDB.md"]
             },
             {
-                "files": ["articles/**.md", "articles/**/toc.yml", "toc.yml", "*.md"]
+                "files": ["*.md"]
             }
         ],
         "resource": [
             {
-                "files": ["images/**", "images/mongodb-logo.svg"]
+                "files": ["images/**"]
             }
         ],
-        "output": "_site",
         "globalMetadataFiles": [],
         "fileMetadataFiles": [],
-        "template": ["default", "modern"],
+        "template": ["default", "modern", "mongo-apidocs"],
         "postProcessors": [],
         "keepFileLink": false,
         "disableGitFeatures": false,
         "globalMetadata": {
             "_appTitle": "MongoDB EF Core Provider API Reference",
             "_appFooter": "&copy; 2023 MongoDB, Inc.",
-            "_appLogoPath": "images/mongodb-logo.svg"
+            "_appLogoPath": "images/mongodb-logo.svg",
+            "_disableContribution": "true"
         }
     }
 }
diff --git a/apidocs/images/mongodb-logo.svg b/apidocs/images/mongodb-logo.svg
@@ -1,6 +1,7 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="130"
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
   viewBox="0 -3 130 42"
-  height="42">
+  height="50"
+  width="150">
   <path
     d="M14 12.68C12.33 5.32 8.85 3.36 7.97 1.97 7.6 1.36 7.28.73 7 .08c-.05.65-.13 1.07-.69 1.56C5.19 2.63.45 6.49.05 14.86c-.37 7.8 5.73 12.61 6.54 13.1.62.31 1.38.01 1.74-.27 2.94-2.02 6.96-7.4 5.67-15.01"
     fill="#10aa50" />
@@ -22,4 +23,4 @@
     <path id="B"
       d="M42.53 16.4c-.39-.01-.78.1-1.11.31-.81.49-1.22 1.47-1.22 2.92 0 2.7 1.35 4.59 3.29 4.59.52.02 1.03-.16 1.42-.5.6-.49.91-1.48.91-2.87 0-2.66-1.32-4.45-3.29-4.45m.37 8.82c-3.5 0-4.74-2.57-4.74-4.97 0-1.68.69-2.99 2.04-3.9a6.2 6.2 0 0 1 3.15-.93c2.67 0 4.53 1.92 4.53 4.67 0 1.87-.74 3.34-2.15 4.27a6.1 6.1 0 0 1-2.82.86" />
   </defs>
-</svg>
+</svg>
diff --git a/apidocs/index.md b/apidocs/index.md
@@ -0,0 +1,3 @@
+---
+redirect_url: api/index.html
+---
diff --git a/apidocs/mongo-apidocs/public/main.css b/apidocs/mongo-apidocs/public/main.css
@@ -0,0 +1,63 @@
+﻿:root {
+    --bs-font-sans-serif: 'Euclid Circular A','Helvetica Neue',Helvetica,Arial,sans-serif;
+    --bs-font-monospace: "Source Code Pro", Menlo, monospace;
+}
+
+h1, h2, h3 {
+    font-family: 'MongoDB Value Serif','Times New Roman',serif;
+    color: rgb(0, 104, 74);
+    font-weight: bold;
+}
+
+dt {
+    font-weight: normal;
+}
+
+@font-face {
+    font-family: Euclid Circular A;
+    src: url(https://static.mongodb.com/com/fonts/EuclidCircularA-Regular-WebXL.woff2) format('woff2');
+    font-weight: normal;
+    font-display: swap;
+}
+
+@font-face {
+    font-family: Euclid Circular A;
+    src: url(https://static.mongodb.com/com/fonts/EuclidCircularA-Medium-WebXL.woff2) format('woff2');
+    font-weight: 500;
+    font-display: swap;
+}
+
+@font-face {
+    font-family: MongoDB Value Serif;
+    src: url(https://static.mongodb.com/com/fonts/MongoDBValueSerif-Regular.woff2) format('woff2');
+    font-weight: normal;
+    font-display: swap;
+}
+
+@font-face {
+    font-family: MongoDB Value Serif;
+    src: url(https://static.mongodb.com/com/fonts/MongoDBValueSerif-Medium.woff2) format('woff2');
+    font-weight: 500;
+    font-display: swap;
+}
+
+@font-face {
+    font-family: MongoDB Value Serif;
+    src: url(https://static.mongodb.com/com/fonts/MongoDBValueSerif-Bold.woff2) format('woff2');
+    font-weight: bold;
+    font-display: swap;
+}
+
+@font-face {
+    font-family: Source Code Pro;
+    src: url(https://static.mongodb.com/com/fonts/SourceCodePro-Regular.ttf) format('truetype');
+    font-weight: normal;
+    font-display: swap;
+}
+
+@font-face {
+    font-family: Source Code Pro;
+    src: url(https://static.mongodb.com/com/fonts/SourceCodePro-Medium.ttf) format('truetype');
+    font-weight: 500;
+    font-display: swap;
+}
diff --git a/docfx_project/.gitignore b/docfx_project/.gitignore
diff --git a/docfx_project/api/.gitignore b/docfx_project/api/.gitignore
diff --git a/docfx_project/index.md b/docfx_project/index.md
diff --git a/docfx_project/toc.yml b/docfx_project/toc.yml
diff --git a/evergreen/build-apidocs.sh b/evergreen/build-apidocs.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -o errexit  # Exit the script with error if any of the commands fail
+
+if [ -z "$PACKAGE_VERSION" ]; then
+  PACKAGE_VERSION=$(sh ./evergreen/generate-version.sh)
+  echo Calculated PACKAGE_VERSION value: "$PACKAGE_VERSION"
+fi
+
+echo "Configure dotnet cli to use local manifest"
+dotnet new tool-manifest --force
+
+echo "Installing docfx tool"
+dotnet tool install docfx --version "2.72.1" --local --verbosity q
+
+echo "Building the api-docs"
+dotnet tool run docfx metadata ./apidocs/docfx.json --property ProduceReferenceAssembly=true
+dotnet tool run docfx build ./apidocs/docfx.json -o:./artifacts/apidocs/"$PACKAGE_VERSION"
diff --git a/evergreen/evergreen.yml b/evergreen/evergreen.yml
@@ -38,17 +38,16 @@ functions:
         shell: bash
         working_dir: mongo-efcore-provider
         script: |
-          echo "${BUILD_TARGET}"
           # Get the current unique version of this checkout
           if [ "${is_patch}" = "true" ]; then
             CURRENT_VERSION=$(git describe)-patch-${version_id}
           else
             CURRENT_VERSION=latest
           fi
 
-          if [ "${BUILD_TARGET}" != "tests" ]; then
-              PACKAGE_VERSION=$(BUILD_TARGET="${BUILD_TARGET}" sh ./evergreen/packages-version.sh)
-           fi
+          if [ "${BUILD_TARGET}" = "release" ]; then
+            PACKAGE_VERSION=$(BUILD_TARGET="${BUILD_TARGET}" sh ./evergreen/generate-version.sh)
+          fi
 
           export DRIVERS_TOOLS="$(pwd)/../drivers-tools"
           export DOTNET_SDK_PATH="$(pwd)/../.dotnet"
@@ -290,6 +289,35 @@ functions:
         remote_file: ${revision}/${PACKAGE_ID}.${PACKAGE_VERSION}.snupkg
         bucket: ${aws_upload_bucket}
 
+  build-apidocs:
+    - command: shell.exec
+      params:
+        shell: bash
+        working_dir: mongo-efcore-provider
+        script: |
+          ${PREPARE_SHELL}
+          if ! [[ "$PACKAGE_VERSION" =~ ^[0-9]+\.[0-9]+\.0$ ]]; then
+            echo "Skip api docs generating for the patch release"
+            exit 0
+          fi
+          ./evergreen/build-apidocs.sh
+
+  upload-apidocs:
+    - command: shell.exec
+      params:
+        shell: bash
+        working_dir: mongo-efcore-provider
+        env:
+          GITHUB_USER: ${github_user}
+          GITHUB_APIKEY: ${github_apikey}
+        script: |
+          ${PREPARE_SHELL}
+          if ! [[ "$PACKAGE_VERSION" =~ ^[0-9]+\.[0-9]+\.0$ ]]; then
+            echo "Skip api docs generating for the patch release"
+            exit 0
+          fi
+          ./evergreen/upload-apidocs.sh
+
 pre:
   - func: fetch-source
   - func: prepare-resources
@@ -324,6 +352,11 @@ tasks:
           PACKAGE_ID: "MongoDB.EntityFrameworkCore"
       - func: packages-smoke-tests
 
+  - name: generate-apidocs
+    commands:
+      - func: build-apidocs
+      - func: upload-apidocs
+
   - name: push-packages
     commands:
       - func: download-package
@@ -417,10 +450,10 @@ axes:
         display_name: "tests"
         variables:
           BUILD_TARGET: "tests"
-      - id: "package"
-        display_name: "package"
+      - id: "release"
+        display_name: "release"
         variables:
-          BUILD_TARGET: "package"
+          BUILD_TARGET: "release"
 
 buildvariants:
 - matrix_name: main-tests
@@ -453,7 +486,7 @@ buildvariants:
 
 - matrix_name: pack-packages
   matrix_spec:
-    build-target: "package"
+    build-target: "release"
   display_name: "Package Pack"
   run_on: ubuntu2004-small
   tags: ["pack-packages", "release_tag"]
@@ -467,7 +500,7 @@ buildvariants:
     os: "*"
     driver: "latest"
     target_runtime: "*"
-    build-target: "package"
+    build-target: "release"
   display_name: "${target_runtime} smoke tests on ${os}"
   tags: ["package-tests", "release_tag"]
   tasks:
@@ -477,10 +510,22 @@ buildvariants:
         - name: pack-packages
           variant: .pack-packages
 
+- matrix_name: generate-apidocs
+  matrix_spec:
+    build-target: "release"
+  display_name: "Generate API Documentation"
+  run_on: ubuntu2004-small
+  tags: ["generate-apidocs", "release_tag"]
+  tasks:
+    - name: generate-apidocs
+      git_tag_only: true
+      depends_on:
+        - name: packages-tests
+          variant: .package-tests
 
 - matrix_name: push-packages
   matrix_spec:
-    build-target: "package"
+    build-target: "release"
   display_name: "Package Push"
   run_on: ubuntu2004-small
   tags: ["push-packages", "release_tag"]
@@ -492,3 +537,5 @@ buildvariants:
           variant: .pack-packages
         - name: packages-tests
           variant: .package-tests
+        - name: generate-apidocs
+          variant: .generate-apidocs
diff --git a/evergreen/upload-apidocs.sh b/evergreen/upload-apidocs.sh
@@ -0,0 +1,16 @@
+﻿#!/usr/bin/env bash
+set -o errexit  # Exit the script with error if any of the commands fail
+
+DOCS_REPO="https://${GITHUB_USER}:${GITHUB_APIKEY}@github.com/mongodb/mongo-efcore-provider.git"
+
+echo "Prepare github docs"
+git clone "$DOCS_REPO" ./gh-pages/ --branch gh-pages --single-branch
+
+mkdir ./gh-pages/"$PACKAGE_VERSION"/
+cp -r ./artifacts/apidocs/"$PACKAGE_VERSION"/. ./gh-pages/"$PACKAGE_VERSION"/
+
+cd ./gh-pages
+
+git add --all
+git commit -m "Add $PACKAGE_VERSION Api docs" --author="Build Agent<dbx-csharp-dotnet@mongodb.com>"
+git push --repo="$DOCS_REPO"

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+---`
	`2`	`+redirect_url: ../index.html`
	`3`	`+---`
Original file line number	Diff line number	Diff line change
`@@ -21,28 +21,28 @@`
`21`	`21`	`"build": {`
`22`	`22`	`"content": [`
`23`	`23`	`{`
`24`		`- "files": ["api/**.yml", "api/index.md"]`
	`24`	`+ "files": ["api/**.yml", "api/index.md", "api/MongoDB.md"]`
`25`	`25`	`},`
`26`	`26`	`{`
`27`		`- "files": ["articles/.md", "articles//toc.yml", "toc.yml", "*.md"]`
	`27`	`+ "files": ["*.md"]`
`28`	`28`	`}`
`29`	`29`	`],`
`30`	`30`	`"resource": [`
`31`	`31`	`{`
`32`		`- "files": ["images/**", "images/mongodb-logo.svg"]`
	`32`	`+ "files": ["images/**"]`
`33`	`33`	`}`
`34`	`34`	`],`
`35`		`- "output": "_site",`
`36`	`35`	`"globalMetadataFiles": [],`
`37`	`36`	`"fileMetadataFiles": [],`
`38`		`- "template": ["default", "modern"],`
	`37`	`+ "template": ["default", "modern", "mongo-apidocs"],`
`39`	`38`	`"postProcessors": [],`
`40`	`39`	`"keepFileLink": false,`
`41`	`40`	`"disableGitFeatures": false,`
`42`	`41`	`"globalMetadata": {`
`43`	`42`	`"_appTitle": "MongoDB EF Core Provider API Reference",`
`44`	`43`	`"_appFooter": "© 2023 MongoDB, Inc.",`
`45`		`- "_appLogoPath": "images/mongodb-logo.svg"`
	`44`	`+ "_appLogoPath": "images/mongodb-logo.svg",`
	`45`	`+ "_disableContribution": "true"`
`46`	`46`	`}`
`47`	`47`	`}`
`48`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+---`
	`2`	`+redirect_url: api/index.html`
	`3`	`+---`