Add typedoc report and GH Pages publishing (#402)

* Add typedoc report and GH Pages publishing * Fix contributing instructions * Add dids package to the build
decentralized-identity · Mar 19, 2024 · bf1de7b · bf1de7b
1 parent 3048ca8
commit bf1de7b
Show file tree

Hide file tree

Showing 5 changed files with 116 additions and 19 deletions.
diff --git 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
@@ -38,10 +38,24 @@ 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-markdown
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/api/README.md
+            - file: packages/crypto/src/index.ts
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/crypto/README.md
+            - file: packages/crypto-aws-kms/src/index.ts
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/crypto-aws-kms/README.md
+            - file: packages/dids/src/index.ts
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/dids/README.md
 
       - 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
@@ -37,21 +37,35 @@ jobs:
       - 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
+      - name: Build all workspace packages
+        run: npm run build
+
+      - name: TBDocs Reporter
+        id: tbdocs-reporter-protocol
+        uses: TBD54566975/tbdocs@main
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fail_on_error: true
+          entry_points: |
+            - file: packages/api/src/index.ts
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/api/README.md
+            - file: packages/crypto/src/index.ts
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/crypto/README.md
+            - file: packages/crypto-aws-kms/src/index.ts
+              docsReporter: typedoc
+              docsGenerator: typedoc-html
+              readmeFile: packages/crypto-aws-kms/README.md
 
       - name: Upload documentation artifacts
         uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 #v3.1.3
         with:
-          name: jsdoc
-          path: ./docs
+          name: tbdocs-output
+          path: ./.tbdocs
 
   deploy:
     # Add a dependency to the build job
@@ -77,16 +91,16 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v3
 
-      - name: Download JSDoc artifacts
+      - name: Download TBDocs Artifacts
         uses: actions/download-artifact@v3
         with:
-          name: jsdoc
-          path: ./docs
+          name: tbdocs-output
+          path: ./tbdocs
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
-          path: "./docs"
+          path: "./.tbdocs/docs"
 
       - name: Deploy to GitHub Pages
         id: deployment

diff --git a/.gitignore b/.gitignore
@@ -159,4 +159,7 @@ dist
 # IntelliJ
 .idea
 
-results.xml
+results.xml
+
+.tbdocs
+temp
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -94,7 +94,7 @@ to your valuable work:
   rebase atop the upstream `main` branch. This will limit the potential for merge
   conflicts during review, and helps keep the audit trail clean. A good writeup for
   how this is done is
- [this beginner's guide to squashing commits](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
+  [this beginner's guide to squashing commits](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
   having trouble - feel free to ask a member or the community for help or leave the commits as-is, and flag that you'd like
   rebasing assistance in your PR! We're here to support you.
 - Open a PR in the project to bring in the code from your feature branch.
@@ -134,6 +134,26 @@ To maintain the robustness and reliability of the codebase, we highly value test
   [Discord](https://discord.com/channels/937858703112155166/969272658501976117)
   channel.
 
+### Documentation Generator
+
+We are using [tbdocs](https://github.com/TBD54566975/tbdocs) to check, generate and publish our SDK API Reference docs automatically to GH Pages.
+
+To see if the docs are being generated properly without errors, and to preview the generated docs locally execute the following script:
+
+```sh
+./scripts/tbdocs-check-local.sh
+
+# to see if there are any doc errors
+open .tbdocs/docs-report.md
+
+# to serve the generated docs locally using a static server (e.g. `npm i -g http-server`)
+http-server .tbdocs/docs
+```
+
+The errors can be found at `./tbdocs/summary.md`
+
+_PS: You need to have docker installed on your computer._
+
 ### Project Versioning Guidelines
 
 This section provides guidelines for versioning Web5 JS packages. All releases are published to the

diff --git a/scripts/tbdocs-check-local.sh b/scripts/tbdocs-check-local.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+
+mkdir -p .tbdocs
+
+SUMMARY_FILE=.tbdocs/summary.md
+
+rm -f ${SUMMARY_FILE}
+touch ${SUMMARY_FILE}
+
+INPUT_ENTRY_POINTS="
+- file: packages/api/src/index.ts
+  docsReporter: typedoc
+  docsGenerator: typedoc-html
+  readmeFile: packages/api/README.md
+- file: packages/crypto/src/index.ts
+  docsReporter: typedoc
+  docsGenerator: typedoc-html
+  readmeFile: packages/crypto/README.md
+- file: packages/crypto-aws-kms/src/index.ts
+  docsReporter: typedoc
+  docsGenerator: typedoc-html
+  readmeFile: packages/crypto-aws-kms/README.md
+- file: packages/dids/src/index.ts
+  docsReporter: typedoc
+  docsGenerator: typedoc-html
+  readmeFile: packages/dids/README.md
+"
+
+# Default docker image
+DOCKER_IMAGE="ghcr.io/tbd54566975/tbdocs:main"
+
+# Check for --local-image flag and update DOCKER_IMAGE if present
+for arg in "$@"
+do
+    if [ "$arg" == "--local-image" ]; then
+        DOCKER_IMAGE="tbdocs:latest"
+    fi
+done
+
+docker run -v $(pwd):/github/workspace/ \
+   --workdir /github/workspace          \
+   -e "GITHUB_REPOSITORY=TBD54566975/web5-js" \
+   -e "GITHUB_STEP_SUMMARY=${SUMMARY_FILE}" \
+   -e "INPUT_ENTRY_POINTS=${INPUT_ENTRY_POINTS}" \
+   -e "INPUT_GROUP_DOCS=true" \
+   ${DOCKER_IMAGE}