From aa042ba61bba08643888e1bcc7fcbdfff4b13ad8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:25:28 +0100 Subject: [PATCH] API Reference Documentation (#8228) (#8417) * Add `docfx` config * Implement automatic API docs generation Co-authored-by: Florian Bernd --- .github/workflows/docfx.yml | 76 +++++++++++++++++++++++++++++ .github/workflows/docfx_manual.yml | 12 +++++ .github/workflows/release_stack.yml | 8 +++ docfx/.gitignore | 2 + docfx.json => docfx/docfx.json | 5 +- docfx/images/logo.svg | 16 ++++++ docfx/index.md | 9 ++++ docfx/toc.yml | 2 + 8 files changed, 128 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docfx.yml create mode 100644 .github/workflows/docfx_manual.yml create mode 100644 docfx/.gitignore rename docfx.json => docfx/docfx.json (84%) create mode 100644 docfx/images/logo.svg create mode 100644 docfx/index.md create mode 100644 docfx/toc.yml diff --git a/.github/workflows/docfx.yml b/.github/workflows/docfx.yml new file mode 100644 index 00000000000..e99719455d4 --- /dev/null +++ b/.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 diff --git a/.github/workflows/docfx_manual.yml b/.github/workflows/docfx_manual.yml new file mode 100644 index 00000000000..5c5207a7f91 --- /dev/null +++ b/.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' diff --git a/.github/workflows/release_stack.yml b/.github/workflows/release_stack.yml index ab1835054d6..81a406e0a56 100644 --- a/.github/workflows/release_stack.yml +++ b/.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' diff --git a/docfx/.gitignore b/docfx/.gitignore new file mode 100644 index 00000000000..0f17bd3852a --- /dev/null +++ b/docfx/.gitignore @@ -0,0 +1,2 @@ +_site +api diff --git a/docfx.json b/docfx/docfx.json similarity index 84% rename from docfx.json rename to docfx/docfx.json index 3b0069106e2..dc98c5280f9 100644 --- a/docfx.json +++ b/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 diff --git a/docfx/images/logo.svg b/docfx/images/logo.svg new file mode 100644 index 00000000000..be8c924e331 --- /dev/null +++ b/docfx/images/logo.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/docfx/index.md b/docfx/index.md new file mode 100644 index 00000000000..cb05b109570 --- /dev/null +++ b/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. diff --git a/docfx/toc.yml b/docfx/toc.yml new file mode 100644 index 00000000000..a2a2fa2bc1f --- /dev/null +++ b/docfx/toc.yml @@ -0,0 +1,2 @@ +- name: API + href: api/ \ No newline at end of file