From bf1de7b4f26a86264844b53a7ecc73c9524afd14 Mon Sep 17 00:00:00 2001 From: Leo Ribeiro Date: Sat, 10 Feb 2024 05:43:52 -0500 Subject: [PATCH] Add typedoc report and GH Pages publishing (#402) * Add typedoc report and GH Pages publishing * Fix contributing instructions * Add dids package to the build --- .github/workflows/docs-ci.yml | 20 +++++++++++-- .github/workflows/docs-publish.yml | 42 ++++++++++++++++++--------- .gitignore | 5 +++- CONTRIBUTING.md | 22 +++++++++++++- scripts/tbdocs-check-local.sh | 46 ++++++++++++++++++++++++++++++ 5 files changed, 116 insertions(+), 19 deletions(-) create mode 100755 scripts/tbdocs-check-local.sh diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index e470ca47d..d6e13c307 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 @@ -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 index d39ccf0ec..eb63f7b02 100644 --- 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 index e0b5c2fdb..b467365cc 100644 --- a/.gitignore +++ b/.gitignore @@ -159,4 +159,7 @@ dist # IntelliJ .idea -results.xml \ No newline at end of file +results.xml + +.tbdocs +temp \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3949c38c..2b39d4b47 100644 --- 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 new file mode 100755 index 000000000..ddd7b1ba5 --- /dev/null +++ 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} \ No newline at end of file