From f79d33671bfeb2d381f84ecc3e3b744adc9cd1c5 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 29 Jun 2021 14:35:18 -0400 Subject: [PATCH 1/2] chore: use typedoc to build sdk reference --- .github/workflows/docs.yaml | 54 +++++++++++++++++++++++++++++++++++++ README.md | 13 ++++----- package.json | 6 ++--- tsconfig.json | 43 ++++++++++++++++++++++++++++- 4 files changed, 106 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000000..f07727a110 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,54 @@ +name: Deploy API Documentation + +on: + release: + types: [published] + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + + - uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: restore lock files + uses: actions/cache@master # must use unreleased master to cache multiple paths + id: cache + with: + # must be done before bootstrap to not include node_modules files in the cache paths + path: | + package-lock.json + packages/*/package-lock.json + benchmark/*/package-lock.json + backwards-compatability/*/package-lock.json + metapackages/*/package-lock.json + packages/*/package-lock.json + integration-tests/*/package-lock.json + key: ${{ runner.os }}-unit_test-${{ matrix.node_version }}-${{ hashFiles('**/package.json') }} + - name: Install and Build (cache miss) 🔧 + if: steps.cache.outputs.cache-hit != 'true' + run: | + npm install --ignore-scripts + npx lerna bootstrap --no-ci + npm run compile + + - name: Install and Build (cache hit) 🔧 + if: steps.cache.outputs.cache-hit == 'true' + run: | + npm ci --ignore-scripts + npx lerna bootstrap + npm run compile + + - name: Build Docs + run: npm run docs + + - name: Deploy Documentation 🚀 + uses: JamesIves/github-pages-deploy-action@releases/v3 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages # The branch the action should deploy to. + FOLDER: docs # The folder the action should deploy. diff --git a/README.md b/README.md index ec804f8d29..25420812c4 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,11 @@ ---

- Getting Started + Getting Started   •   - API Documentation + API Reference   •   + SDK Reference

@@ -28,13 +29,13 @@

- Contributing + Contributing   •   - Development Guide + Development Guide   •   - Benchmarks + Benchmarks   •   - Examples + Examples

diff --git a/package.json b/package.json index 6050ef0784..dffbba47ed 100644 --- a/package.json +++ b/package.json @@ -22,9 +22,8 @@ "codecov": "lerna run codecov", "codecov:browser": "lerna run codecov:browser", "predocs-test": "npm run docs", - "docs-test": "lerna run docs-test", - "docs": "lerna run docs", - "docs-deploy": "gh-pages --dist packages/opentelemetry-api/docs/out", + "docs": "typedoc", + "docs-deploy": "gh-pages --dist docs", "lint": "lerna run lint", "lint:changed": "lerna run --concurrency 1 --stream lint --since HEAD --exclude-dependents", "lint:fix": "lerna run lint:fix", @@ -62,6 +61,7 @@ "lerna": "3.22.1", "lerna-changelog": "1.0.1", "markdownlint-cli": "0.27.1", + "typedoc": "0.21.2", "typescript": "4.3.4", "update-ts-references": "2.4.0" }, diff --git a/tsconfig.json b/tsconfig.json index 44e36c8025..e3c5a0a624 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,6 +1,47 @@ { "extends": "./tsconfig.base.json", "files": [], + "typedocOptions": { + "packages": [ + "packages/opentelemetry-api-metrics", + "packages/opentelemetry-context-async-hooks", + "packages/opentelemetry-context-zone", + "packages/opentelemetry-context-zone-peer-dep", + "packages/opentelemetry-core", + "packages/opentelemetry-exporter-collector", + "packages/opentelemetry-exporter-collector-grpc", + "packages/opentelemetry-exporter-collector-proto", + "packages/opentelemetry-exporter-jaeger", + "packages/opentelemetry-exporter-prometheus", + "packages/opentelemetry-exporter-zipkin", + "packages/opentelemetry-instrumentation", + "packages/opentelemetry-instrumentation-fetch", + "packages/opentelemetry-instrumentation-grpc", + "packages/opentelemetry-instrumentation-http", + "packages/opentelemetry-instrumentation-xml-http-request", + "packages/opentelemetry-metrics", + "packages/opentelemetry-node", + "packages/opentelemetry-propagator-b3", + "packages/opentelemetry-propagator-jaeger", + "packages/opentelemetry-resource-detector-aws", + "packages/opentelemetry-resource-detector-gcp", + "packages/opentelemetry-resources", + "packages/opentelemetry-sdk-node", + "packages/opentelemetry-semantic-conventions", + "packages/opentelemetry-shim-opentracing", + "packages/opentelemetry-tracing", + "packages/opentelemetry-web" + ], + "out": "docs", + "exclude": [ + "**/dist/**", + "**/build/**", + "**/node_modules/**", + "**/*.spec.ts" + ], + "name": "OpenTelemetry SDK", + "excludePrivate": true + }, "references": [ { "path": "backwards-compatability/node10" @@ -102,4 +143,4 @@ "path": "integration-tests/propagation-validation-server" } ] -} +} \ No newline at end of file From ca1b4fabb0b79d69908d95638c6999d142455409 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 29 Jun 2021 15:48:30 -0400 Subject: [PATCH 2/2] chore: do not process output with jekyll --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index dffbba47ed..2a6f62e213 100644 --- a/package.json +++ b/package.json @@ -22,8 +22,8 @@ "codecov": "lerna run codecov", "codecov:browser": "lerna run codecov:browser", "predocs-test": "npm run docs", - "docs": "typedoc", - "docs-deploy": "gh-pages --dist docs", + "docs": "typedoc && touch out/.nojekyll", + "docs-deploy": "gh-pages --dotfiles --dist docs", "lint": "lerna run lint", "lint:changed": "lerna run --concurrency 1 --stream lint --since HEAD --exclude-dependents", "lint:fix": "lerna run lint:fix",