From 796aeaaabf4786c4600f00ff0b936bd503e075b6 Mon Sep 17 00:00:00 2001 From: danielwiehl Date: Thu, 31 Oct 2024 08:44:53 +0100 Subject: [PATCH] ci(platform): provide manual deployment of TypeDoc --- ...nual-workflow.publish-developer-guide.yml} | 16 +++--- .../manual-workflow.publish-typedoc.yml | 53 +++++++++++++++++++ .github/workflows/workflow.yml | 8 +-- CONTRIBUTING.md | 8 +-- README.md | 6 +-- .../src/app/app-menu/app-menu.component.html | 2 +- 6 files changed, 73 insertions(+), 20 deletions(-) rename .github/workflows/{manual-workflow.publish-documentation.yml => manual-workflow.publish-developer-guide.yml} (79%) create mode 100644 .github/workflows/manual-workflow.publish-typedoc.yml diff --git a/.github/workflows/manual-workflow.publish-documentation.yml b/.github/workflows/manual-workflow.publish-developer-guide.yml similarity index 79% rename from .github/workflows/manual-workflow.publish-documentation.yml rename to .github/workflows/manual-workflow.publish-developer-guide.yml index c967ecb6..64077e09 100644 --- a/.github/workflows/manual-workflow.publish-documentation.yml +++ b/.github/workflows/manual-workflow.publish-developer-guide.yml @@ -1,4 +1,4 @@ -name: Documentation Publication +name: Publish Developer Guide on: workflow_dispatch env: NODE_VERSION: 20.14.0 @@ -19,8 +19,8 @@ jobs: key: node_modules-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} - if: steps.node-modules-cache.outputs.cache-hit != 'true' run: npm ci - publish-documentation: - name: 'Publishing Documentation' + publish-developer-guide: + name: 'Publishing Developer Guide' needs: install runs-on: ubuntu-latest steps: @@ -35,19 +35,19 @@ jobs: key: node_modules-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} - name: 'Reading package.json version of scion/microfrontend-platform' uses: SchweizerischeBundesbahnen/scion-toolkit/.github/actions/package-json@master - id: package-json + id: microfrontend-platform-package-json with: path: projects/scion/microfrontend-platform/package.json - - name: 'Building Reference Documentation (Developer Guide)' - run: npm run microfrontend-platform:adoc -- -a revnumber=${{ steps.package-json.outputs.version }} -a revnumber-dasherized=${{ steps.package-json.outputs.version-dasherized }} - - name: 'Deploying Reference Documentation (Developer Guide) to Vercel' + - name: 'Building Developer Guide' + run: npm run microfrontend-platform:adoc -- -a revnumber=${{ steps.microfrontend-platform-package-json.outputs.version }} -a revnumber-dasherized=${{ steps.microfrontend-platform-package-json.outputs.version-dasherized }} + - name: 'Publishing Developer Guide to Vercel' uses: SchweizerischeBundesbahnen/scion-toolkit/.github/actions/vercel-deploy@master with: dist-folder: dist/microfrontend-platform-developer-guide vercel-token: ${{ secrets.VERCEL_TOKEN }} org-id: ${{ secrets.VERCEL_ORG_ID }} project-id: ${{ secrets.VERCEL_MICROFRONTEND_PLATFORM_DEVELOPER_GUIDE_PROJECT_ID }} - version: ${{ steps.package-json.outputs.version }} + version: ${{ steps.microfrontend-platform-package-json.outputs.version }} aliases: | microfrontend-platform-developer-guide.scion.vercel.app, microfrontend-platform-developer-guide-v%v.scion.vercel.app diff --git a/.github/workflows/manual-workflow.publish-typedoc.yml b/.github/workflows/manual-workflow.publish-typedoc.yml new file mode 100644 index 00000000..220d7d64 --- /dev/null +++ b/.github/workflows/manual-workflow.publish-typedoc.yml @@ -0,0 +1,53 @@ +name: Publish TypeDoc +on: workflow_dispatch +env: + NODE_VERSION: 20.14.0 +jobs: + install: + name: 'Installing NPM modules' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + - name: 'Caching NPM modules if necessary' + uses: actions/cache@v4 + id: node-modules-cache + with: + path: ./node_modules + key: node_modules-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} + - if: steps.node-modules-cache.outputs.cache-hit != 'true' + run: npm ci + publish-typedoc: + name: 'Publishing TypeDoc' + needs: install + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ env.NODE_VERSION }} + - name: 'Restoring NPM modules from cache' + uses: actions/cache@v4 + with: + path: ./node_modules + key: node_modules-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} + - name: 'Reading package.json version of scion/microfrontend-platform' + uses: SchweizerischeBundesbahnen/scion-toolkit/.github/actions/package-json@master + id: microfrontend-platform-package-json + with: + path: projects/scion/microfrontend-platform/package.json + - name: 'Building TypeDoc' + run: npm run microfrontend-platform:typedoc + - name: 'Publishing TypeDoc to Vercel' + uses: SchweizerischeBundesbahnen/scion-toolkit/.github/actions/vercel-deploy@master + with: + dist-folder: dist/microfrontend-platform-api + vercel-token: ${{ secrets.VERCEL_TOKEN }} + org-id: ${{ secrets.VERCEL_ORG_ID }} + project-id: ${{ secrets.VERCEL_MICROFRONTEND_PLATFORM_API_PROJECT_ID }} + version: ${{ steps.microfrontend-platform-package-json.outputs.version }} + aliases: | + microfrontend-platform-api.scion.vercel.app, + microfrontend-platform-api-v%v.scion.vercel.app diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml index 92281747..38efd831 100644 --- a/.github/workflows/workflow.yml +++ b/.github/workflows/workflow.yml @@ -69,9 +69,9 @@ jobs: key: node_modules-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} - name: 'Building @scion/microfrontend-platform' run: npm run microfrontend-platform:build - - name: 'Building API Documentation (TypeDoc)' + - name: 'Building TypeDoc' run: npm run microfrontend-platform:typedoc - - name: 'Building Reference Documentation (Developer Guide)' + - name: 'Building Developer Guide' run: npm run microfrontend-platform:adoc -- -a revnumber=${{ steps.root-package-json.outputs.version }} -a revnumber-dasherized=${{ steps.root-package-json.outputs.version-dasherized }} - uses: actions/upload-artifact@v4 with: @@ -238,7 +238,7 @@ jobs: aliases: | microfrontend-platform-devtools.scion.vercel.app, microfrontend-platform-devtools-v%v.scion.vercel.app - - name: 'Publishing API Documentation (TypeDoc) to Vercel' + - name: 'Publishing TypeDoc to Vercel' uses: SchweizerischeBundesbahnen/scion-toolkit/.github/actions/vercel-deploy@master with: dist-folder: dist/microfrontend-platform-api @@ -249,7 +249,7 @@ jobs: aliases: | microfrontend-platform-api.scion.vercel.app, microfrontend-platform-api-v%v.scion.vercel.app - - name: 'Publishing Reference Documentation (Developer Guide) to Vercel' + - name: 'Publishing Developer Guide to Vercel' uses: SchweizerischeBundesbahnen/scion-toolkit/.github/actions/vercel-deploy@master with: dist-folder: dist/microfrontend-platform-developer-guide diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5e89a99..6131bba2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,10 +82,10 @@ The following is a summary of commands useful for development of `scion-microfro ### Commands for generating the project documentation - `npm run microfrontend-platform:adoc`\ - Use to build the reference documentation (Developer Guide), i.e., creates a HTML file from the AsciiDoc source files. The output is written to `dist/microfrontend-platform-developer-guide`. + Use to build the Developer Guide, i.e., creates a HTML file from the AsciiDoc source files. The output is written to `dist/microfrontend-platform-developer-guide`. - `npm run microfrontend-platform:typedoc`\ - Use to generate the API documentation (TypeDoc) for the SCION Microfrontend Platform library. The output is written to `dist/microfrontend-platform-api`. + Use to generate the TypeDoc for the SCION Microfrontend Platform library. The output is written to `dist/microfrontend-platform-api`. - `npm run changelog`\ Use to generate the changelog based on the commit history. The output is written to `CHANGELOG.md`, which will be included in `docs/site/changelog/changelog.md` using the template `docs/site/changelog/changelog.template.md`. @@ -288,10 +288,10 @@ This chapter describes the tasks to publish a new release to NPM. - Deploys DevTools to Vercel: - https://microfrontend-platform-devtools.scion.vercel.app. - https://microfrontend-platform-devtools-vX-X-X.scion.vercel.app. - - Publishes API Documentation (TypeDoc) to Vercel: + - Publishes TypeDoc to Vercel: - https://microfrontend-platform-api.scion.vercel.app. - https://microfrontend-platform-api-vX-X-X.scion.vercel.app. - - Publishes Reference Documentation (Developer Guide) to Vercel: + - Publishes Developer Guide to Vercel: - https://microfrontend-platform-developer-guide.scion.vercel.app. - https://microfrontend-platform-developer-guide-vX-X-X.scion.vercel.app. 1. Migrate the [Getting Started Guide][link-getting-started-guide-repo] Git Repo if necessary. diff --git a/README.md b/README.md index 8679c352..841dee27 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,11 @@ SCION Microfrontend Platform enables you to successfully implement a framework-a #### Documentation -- [**Reference Documentation**][link-developer-guide]\ +- [**Developer Guide**][link-developer-guide]\ Read our Developer Guide to learn more about the core concepts and configuration of the platform. -- [**API Documentation**][link-reference-documentation]\ - Consult our Public API documentation for a complete overview of the API. +- [**TypeDoc**][link-reference-documentation]\ + Consult our API documentation for a complete overview of the API. #### Miscellaneous diff --git a/apps/microfrontend-platform-devtools/src/app/app-menu/app-menu.component.html b/apps/microfrontend-platform-devtools/src/app/app-menu/app-menu.component.html index f5a3f555..56ca3252 100644 --- a/apps/microfrontend-platform-devtools/src/app/app-menu/app-menu.component.html +++ b/apps/microfrontend-platform-devtools/src/app/app-menu/app-menu.component.html @@ -26,7 +26,7 @@