chore: use typedoc to build sdk reference (#2308)

Co-authored-by: Valentin Marchaud <contact@vmarchaud.fr>

.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.

README.md

@@ -2,10 +2,11 @@
 ---
 <p align="center">
   <strong>
-    <a href="getting-started/README.md">Getting Started<a/>
+    <a href="getting-started/README.md">Getting Started</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
-    <a href="https://open-telemetry.github.io/opentelemetry-js">API Documentation<a/>
+    <a href="https://open-telemetry.github.io/opentelemetry-js-api">API Reference</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
+    <a href="https://open-telemetry.github.io/opentelemetry-js">SDK Reference</a>
   </strong>
 </p>
 
@@ -28,13 +29,13 @@
 
 <p align="center">
   <strong>
-    <a href="CONTRIBUTING.md">Contributing<a/>
+    <a href="CONTRIBUTING.md">Contributing</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
-    <a href="doc/development-guide.md">Development Guide<a/>
+    <a href="doc/development-guide.md">Development Guide</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
-    <a href="benchmark/README.md">Benchmarks<a/>
+    <a href="benchmark/README.md">Benchmarks</a>
     &nbsp;&nbsp;&bull;&nbsp;&nbsp;
-    <a href="examples/">Examples<a/>
+    <a href="examples/">Examples</a>
   </strong>
 </p>
 

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 && 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",
@@ -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.5",
     "update-ts-references": "2.4.0"
   },

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"
     }
   ]
-}
+}