Improve reference documentation (#8418)

Author: flobernd

.github/workflows/docfx.yml

@@ -1,17 +1,20 @@
 name: 'CD'
 
-# TODO: Remove 'stack'
-
 on:
   workflow_call:
     inputs:
-      release_tag:
-        description: 'The release tag (release version)'
+      target_branch:
+        description: 'The target branch to which the documentation should be pushed to.'
         type: 'string'
         required: true
+      name:
+        description: 'The name to use for the documentation folder (defaults to the name of the current ref)'
+        type: 'string'
+        required: false
+        default: ${{ github.ref_name }}
 
 concurrency:
-  group: 'docfx-stack'
+  group: 'docfx'
   cancel-in-progress: false
 
 env:
@@ -26,15 +29,9 @@ env:
 
 jobs:
   docfx:
-    name: 'Generate API Documentation'
+    name: 'DocFx'
     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'
 
@@ -47,6 +44,7 @@ jobs:
         run: |-
           dotnet tool update -g docfx
 
+      # TODO: Remove 'stack'
       - name: '.NET Cache Packages'
         uses: 'actions/cache@v4'
         with:
@@ -63,14 +61,14 @@ jobs:
       - name: 'Checkout'
         uses: 'actions/checkout@v4'
         with:
-          ref: 'refdoc'
+          ref: ${{ inputs.target_branch }}
 
       - name: 'Commit'
         run: |-
-          rm -r "./${{ steps.version.outputs.version }}" || true
-          mv ../_site "./${{ steps.version.outputs.version }}"
+          rm -r "./${{ inputs.name }}" || true
+          mv ../_site "./${{ inputs.name }}"
           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 add -A
+          git commit -am "Add ${{ inputs.name }}"
           git push

.github/workflows/docfx_manual.yml

@@ -5,8 +5,8 @@ on:
 
 jobs:
   docfx:
-    name: 'Generate Documentation'
+    name: 'DocFx'
     uses: ./.github/workflows/docfx.yml
     with:
-      release_tag: ${{ github.ref_name }}
+      target_branch: 'refdoc'
     secrets: 'inherit'

.github/workflows/release_stack.yml

@@ -18,9 +18,10 @@ jobs:
     secrets: 'inherit'
 
   docfx:
-    name: 'Generate Documentation'
+    name: 'DocFx'
     if: ${{ !startsWith(github.event.release.tag_name, 'serverless-') }}
     uses: ./.github/workflows/docfx.yml
     with:
-      release_tag: ${{ github.event.release.tag_name }}
+      name: ${{ github.event.release.tag_name }}
+      target_branch: 'refdoc'
     secrets: 'inherit'

README.md

@@ -58,6 +58,8 @@ Please refer to
 [the full documentation on elastic.co](https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/index.html)
 for comprehensive information on installation, configuration and usage.
 
+The API reference documentation is available [here](https://elastic.github.io/elasticsearch-net).
+
 ## Versions
 
 ### Elasticsearch 8.x Clusters

docs/usage/index.asciidoc

@@ -6,6 +6,8 @@ The sections below provide tutorials on the most frequently used and some less o
 
 For a full reference, see the {ref}/[Elasticsearch documentation] and in particular the {ref}/rest-apis.html[REST APIs] section. The {net-client} follows closely the JSON structures described there.
 
+A .NET API reference documentation for the Elasticsearch client package is available https://elastic.github.io/elasticsearch-net[here].
+
 If you're new to {es}, make sure also to read {ref}/getting-started.html[Elasticsearch's quick start] that provides a good introduction.
 
 * <<recommendations, Usage recommendations>>