From 134cc2ad4973413c4a104884853a4879d7aa096f Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 14 Dec 2023 17:30:09 -0500 Subject: [PATCH 1/6] Generate docs with TBDocs --- .github/workflows/docs-ci.yml | 4 +- .github/workflows/docs-publish.yml | 108 +++++++++++++++-------------- 2 files changed, 58 insertions(+), 54 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index e470ca47d..c4b5df4be 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -23,7 +23,7 @@ jobs: with: node-version: 18 registry-url: https://registry.npmjs.org/ - cache: 'npm' + cache: "npm" - name: Install dependencies run: npm ci @@ -41,7 +41,7 @@ jobs: entry_points: | - file: packages/api/src/index.ts docsReporter: api-extractor - docsGenerator: typedoc-markdown + docsGenerator: typedoc-html - name: Save Artifacts uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index d39ccf0ec..5027d8638 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -32,62 +32,66 @@ jobs: with: node-version: 18 registry-url: https://registry.npmjs.org/ - cache: 'npm' + cache: "npm" - name: Install dependencies - run: | - npm ci - npm i jsdoc - npm i clean-jsdoc-theme - - - name: Generate documentation - run: | - echo "# Web5 JS SDK" > README-docs.md - echo "Select from the menu on the left to view API reference documentation." >> README-docs.md - npx jsdoc -c jsdoc.json - curl -o docs/favicon.ico https://developer.tbd.website/img/favicon.ico + run: npm ci - - name: Upload documentation artifacts - uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 - with: - name: jsdoc - path: ./docs - - deploy: - # Add a dependency to the build job - needs: build - - # Grant GITHUB_TOKEN the permissions required to make a Pages deployment - permissions: - contents: read # to read from project repo - pages: write # to deploy to Pages - id-token: write # to verify the deployment originates from an appropriate source - - # Deploy to the github-pages environment - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1 + - name: Build all workspace packages + run: npm run build - - name: Setup Pages - uses: actions/configure-pages@v3 - - - name: Download JSDoc artifacts - uses: actions/download-artifact@v3 + - name: TBDocs Reporter + id: tbdocs-reporter-protocol + uses: TBD54566975/tbdocs@leordev/gh-pages-html with: - name: jsdoc - path: ./docs + token: ${{ secrets.GITHUB_TOKEN }} + fail_on_error: true + entry_points: | + - file: packages/api/src/index.ts + docsReporter: api-extractor + docsGenerator: typedoc-html - - name: Upload artifact - uses: actions/upload-pages-artifact@v1 + - name: Upload documentation artifacts + uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 with: - path: "./docs" - - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v2 + name: web5-api-docs + path: ./packages/api/.tbdocs/docs + + # deploy: + # # Add a dependency to the build job + # needs: build + + # # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + # permissions: + # contents: read # to read from project repo + # pages: write # to deploy to Pages + # id-token: write # to verify the deployment originates from an appropriate source + + # # Deploy to the github-pages environment + # environment: + # name: github-pages + # url: ${{ steps.deployment.outputs.page_url }} + + # runs-on: ubuntu-latest + + # steps: + # - name: Checkout + # uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1 + + # - name: Setup Pages + # uses: actions/configure-pages@v3 + + # - name: Download JSDoc artifacts + # uses: actions/download-artifact@v3 + # with: + # name: jsdoc + # path: ./docs + + # - name: Upload artifact + # uses: actions/upload-pages-artifact@v1 + # with: + # path: "./docs" + + # - name: Deploy to GitHub Pages + # id: deployment + # uses: actions/deploy-pages@v2 From 2bc40079a0fbbfff17177d91efc75ae6d9af30d9 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 14 Dec 2023 17:43:48 -0500 Subject: [PATCH 2/6] adjust docs publish workflow --- .github/workflows/docs-publish.yml | 70 +++++++++++++++--------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index 5027d8638..faa3f61db 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -2,10 +2,11 @@ name: Build and Deploy Docs on: - # Runs on pushes targeting the default branch - # push: - # branches: - # - main + # TODO: uncomment before merging + # Runs on new released versions + # release: + # types: + # - published # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -57,41 +58,42 @@ jobs: name: web5-api-docs path: ./packages/api/.tbdocs/docs - # deploy: - # # Add a dependency to the build job - # needs: build + deploy: + # Add a dependency to the build job + needs: build - # # Grant GITHUB_TOKEN the permissions required to make a Pages deployment - # permissions: - # contents: read # to read from project repo - # pages: write # to deploy to Pages - # id-token: write # to verify the deployment originates from an appropriate source + # Grant GITHUB_TOKEN the permissions required to make a Pages deployment + permissions: + contents: read # to read from project repo + pages: write # to deploy to Pages + id-token: write # to verify the deployment originates from an appropriate source - # # Deploy to the github-pages environment - # environment: - # name: github-pages - # url: ${{ steps.deployment.outputs.page_url }} + # Deploy to the github-pages environment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} - # runs-on: ubuntu-latest + runs-on: ubuntu-latest - # steps: - # - name: Checkout - # uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1 + steps: + - name: Checkout + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1 - # - name: Setup Pages - # uses: actions/configure-pages@v3 + - name: Setup Pages + uses: actions/configure-pages@v3 - # - name: Download JSDoc artifacts - # uses: actions/download-artifact@v3 - # with: - # name: jsdoc - # path: ./docs + - name: Download JSDoc artifacts + uses: actions/download-artifact@v3 + with: + name: web5-api-docs + path: ./web5-api-docs - # - name: Upload artifact - # uses: actions/upload-pages-artifact@v1 - # with: - # path: "./docs" + # TODO: uncomment and adjust path before merging + # - name: Upload artifact + # uses: actions/upload-pages-artifact@v1 + # with: + # path: "./docs" - # - name: Deploy to GitHub Pages - # id: deployment - # uses: actions/deploy-pages@v2 + # - name: Deploy to GitHub Pages + # id: deployment + # uses: actions/deploy-pages@v2 From 8fc1c00fcca4d89e36c29b5027ebe79f134e6eab Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Fri, 15 Dec 2023 10:56:03 -0500 Subject: [PATCH 3/6] set tbdocs action version to main branch --- .github/workflows/docs-publish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index faa3f61db..a470924c2 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -43,7 +43,7 @@ jobs: - name: TBDocs Reporter id: tbdocs-reporter-protocol - uses: TBD54566975/tbdocs@leordev/gh-pages-html + uses: TBD54566975/tbdocs@main with: token: ${{ secrets.GITHUB_TOKEN }} fail_on_error: true From bf95d308e449546c1d37bc99139c603c7280cb92 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Fri, 15 Dec 2023 12:09:39 -0500 Subject: [PATCH 4/6] add multiple packages docs --- .github/workflows/docs-ci.yml | 7 +++++ .github/workflows/docs-publish.yml | 42 ++++++++++++++++-------------- 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index c4b5df4be..245dd38bd 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -38,10 +38,17 @@ jobs: token: ${{ secrets.GITHUB_TOKEN }} report_changed_scope_only: false fail_on_error: false + group_docs: true entry_points: | - file: packages/api/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-html + - file: packages/crypto/src/index.ts + docsReporter: api-extractor + docsGenerator: typedoc-html + - file: packages/dids/src/index.ts + docsReporter: api-extractor + docsGenerator: typedoc-html - name: Save Artifacts uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index a470924c2..e9355e277 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -2,11 +2,10 @@ name: Build and Deploy Docs on: - # TODO: uncomment before merging # Runs on new released versions - # release: - # types: - # - published + release: + types: + - published # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -51,12 +50,18 @@ jobs: - file: packages/api/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-html + - file: packages/crypto/src/index.ts + docsReporter: api-extractor + docsGenerator: typedoc-html + - file: packages/dids/src/index.ts + docsReporter: api-extractor + docsGenerator: typedoc-html - name: Upload documentation artifacts uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3 with: - name: web5-api-docs - path: ./packages/api/.tbdocs/docs + name: tbdocs-output + path: ./.tbdocs deploy: # Add a dependency to the build job @@ -82,18 +87,17 @@ jobs: - name: Setup Pages uses: actions/configure-pages@v3 - - name: Download JSDoc artifacts + - name: Download TBDocs Artifacts uses: actions/download-artifact@v3 with: - name: web5-api-docs - path: ./web5-api-docs - - # TODO: uncomment and adjust path before merging - # - name: Upload artifact - # uses: actions/upload-pages-artifact@v1 - # with: - # path: "./docs" - - # - name: Deploy to GitHub Pages - # id: deployment - # uses: actions/deploy-pages@v2 + name: tbdocs-output + path: ./tbdocs + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: "./.tbdocs/docs" + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 From a72bb6c931e8550f78b329af8364e061408d9eaa Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Fri, 15 Dec 2023 12:16:02 -0500 Subject: [PATCH 5/6] fix export * for api-extractor --- packages/crypto/src/index.ts | 5 +++-- packages/dids/src/index.ts | 4 +++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/crypto/src/index.ts b/packages/crypto/src/index.ts index d2952615e..309e5dcc2 100644 --- a/packages/crypto/src/index.ts +++ b/packages/crypto/src/index.ts @@ -1,6 +1,7 @@ export * from './jose.js'; export * from './local-kms-crypto.js'; -export * as utils from './utils.js'; +import * as utils from './utils.js'; +export { utils }; export * from './algorithms/aes-ctr.js'; export * from './algorithms/aes-gcm.js'; @@ -38,4 +39,4 @@ export type * from './types/key-wrapper.js'; export type * from './types/params-direct.js'; export type * from './types/params-enclosed.js'; export type * from './types/params-kms.js'; -export type * from './types/signer.js'; \ No newline at end of file +export type * from './types/signer.js'; diff --git a/packages/dids/src/index.ts b/packages/dids/src/index.ts index f3ff1808b..04864b9d1 100644 --- a/packages/dids/src/index.ts +++ b/packages/dids/src/index.ts @@ -6,4 +6,6 @@ export * from './did-resolver.js'; export * from './resolver-cache-level.js'; export * from './resolver-cache-noop.js'; export * from './types.js'; -export * as utils from './utils.js'; \ No newline at end of file + +import * as utils from './utils.js'; +export { utils }; From fc383de58036028695e6d5691cc5371a327b0f85 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Thu, 4 Jan 2024 13:43:58 -0500 Subject: [PATCH 6/6] add crypto packages to docs pipeline --- .github/workflows/docs-ci.yml | 2 +- .github/workflows/docs-publish.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index 245dd38bd..c14774325 100644 --- a/.github/workflows/docs-ci.yml +++ b/.github/workflows/docs-ci.yml @@ -46,7 +46,7 @@ jobs: - file: packages/crypto/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-html - - file: packages/dids/src/index.ts + - file: packages/crypto-aws-kms/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-html diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml index e9355e277..164590f2e 100644 --- a/.github/workflows/docs-publish.yml +++ b/.github/workflows/docs-publish.yml @@ -53,7 +53,7 @@ jobs: - file: packages/crypto/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-html - - file: packages/dids/src/index.ts + - file: packages/crypto-aws-kms/src/index.ts docsReporter: api-extractor docsGenerator: typedoc-html