API Reference Documentation (#8228) (#8417)

* Add `docfx` config

* Implement automatic API docs generation

Co-authored-by: Florian Bernd <git@flobernd.de>

.github/workflows/docfx.yml

@@ -0,0 +1,76 @@
+name: 'CD'
+
+# TODO: Remove 'stack'
+
+on:
+  workflow_call:
+    inputs:
+      release_tag:
+        description: 'The release tag (release version)'
+        type: 'string'
+        required: true
+
+concurrency:
+  group: 'docfx-stack'
+  cancel-in-progress: false
+
+env:
+  # Configuration
+  GLOBAL_JSON_FILE: 'global.json'
+  CACHE_PATTERNS: '["**/*.[cf]sproj*", "**/*.Build.props"]'
+  # .NET SDK related environment variables
+  DOTNET_NOLOGO: 1
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+  DOTNET_CLI_TELEMETRY_OPTOUT: 1
+  DOTNET_GENERATE_ASPNET_CERTIFICATE: 0
+
+jobs:
+  docfx:
+    name: 'Generate API Documentation'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: 'Parse Version'
+        id: 'version'
+        uses: 'zyactions/semver@v1'
+        with:
+          version: ${{ inputs.release_tag }}
+
+      - name: 'Checkout'
+        uses: 'actions/checkout@v4'
+
+      - name: '.NET Setup'
+        uses: 'actions/setup-dotnet@v4'
+        with:
+          global-json-file: '${{ github.workspace }}/${{ env.GLOBAL_JSON_FILE }}'
+
+      - name: 'DocFX Setup'
+        run: |-
+          dotnet tool update -g docfx
+
+      - name: '.NET Cache Packages'
+        uses: 'actions/cache@v4'
+        with:
+          path: '~/.nuget/packages'
+          key: '${{ runner.os }}-nuget-stack-${{ hashFiles(fromJson(env.CACHE_PATTERNS)) }}'
+          restore-keys: '${{ runner.os }}-nuget-stack-'
+
+      - name: 'DocFx Build'
+        working-directory: 'docfx'
+        run: |-
+          docfx docfx.json
+          mv ./_site ./../..
+
+      - name: 'Checkout'
+        uses: 'actions/checkout@v4'
+        with:
+          ref: 'refdoc'
+
+      - name: 'Commit'
+        run: |-
+          rm -r "./${{ steps.version.outputs.version }}" || true
+          mv ../_site "./${{ steps.version.outputs.version }}"
+          git config --global user.name '${{ github.actor }}'
+          git config --global user.email '${{ github.actor }}@users.noreply.github.com'
+          git add .
+          git commit -am "Add ${{ steps.version.outputs.version }}"
+          git push

.github/workflows/docfx_manual.yml

@@ -0,0 +1,12 @@
+name: 'DocFx'
+
+on:
+  workflow_dispatch:
+
+jobs:
+  docfx:
+    name: 'Generate Documentation'
+    uses: ./.github/workflows/docfx.yml
+    with:
+      release_tag: ${{ github.ref_name }}
+    secrets: 'inherit'

.github/workflows/release_stack.yml

@@ -16,3 +16,11 @@ jobs:
       release_tag: ${{ github.event.release.tag_name }}
       release_body: ${{ github.event.release.body }}
     secrets: 'inherit'
+
+  docfx:
+    name: 'Generate Documentation'
+    if: ${{ !startsWith(github.event.release.tag_name, 'serverless-') }}
+    uses: ./.github/workflows/docfx.yml
+    with:
+      release_tag: ${{ github.event.release.tag_name }}
+    secrets: 'inherit'

docfx/.gitignore

@@ -0,0 +1,2 @@
+_site
+api

docfx.json → docfx/docfx.json

@@ -3,9 +3,9 @@
     {
       "src": [
         {
-          "src": "./src/Elastic.Clients.Elasticsearch",
+          "src": "../src",
           "files": [
-            "**/*.csproj"
+            "**/Elastic.Clients.Elasticsearch.csproj"
           ]
         }
       ],
@@ -38,6 +38,7 @@
     "globalMetadata": {
       "_appName": "Elasticsearch.NET",
       "_appTitle": "Elasticsearch.NET",
+      "_appLogoPath": "images/logo.svg",
       "_enableSearch": true,
       "_disableContribution": true,
       "pdf": false

docfx/index.md

@@ -0,0 +1,9 @@
+---
+_layout: landing
+---
+
+# Elasticsearch .NET API
+
+This is the home of the Elasticsearch .NET Client API Reference Documentation.
+
+Please click on `API` in the top menu to get to the API overview.

docfx/toc.yml

@@ -0,0 +1,2 @@
+- name: API
+  href: api/