ci(platform): provide manual deployment of TypeDoc

Author: danielwiehl

.github/workflows/manual-workflow.publish-documentation.yml renamed to .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

.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

.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

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.

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
 

apps/microfrontend-platform-devtools/src/app/app-menu/app-menu.component.html

@@ -26,7 +26,7 @@
 
     <ul>
       <li><a href="https://microfrontend-platform-developer-guide.scion.vercel.app/" target="_blank" rel="noopener noreferrer">Developer Guide</a></li>
-      <li><a href="https://microfrontend-platform-api.scion.vercel.app/" target="_blank" rel="noopener noreferrer">API Documentation</a></li>
+      <li><a href="https://microfrontend-platform-api.scion.vercel.app/" target="_blank" rel="noopener noreferrer">TypeDoc</a></li>
       <li><a href="https://github.com/SchweizerischeBundesbahnen/scion-microfrontend-platform/issues" target="_blank" rel="noopener noreferrer">Report an Issue</a></li>
       <li><a href="https://github.com/SchweizerischeBundesbahnen/scion-microfrontend-platform/blob/master/docs/site/getting-started/getting-started.md" target="_blank" rel="noopener noreferrer">Getting Started</a></li>
       <li><a href="https://github.com/SchweizerischeBundesbahnen/scion-microfrontend-platform" target="_blank" rel="noopener noreferrer">Visit us on GitHub</a></li>