deploy the API reference with the documentation

.github/workflows/deploy-documentation.yml → .github/workflows/deploy-website.yml

@@ -1,11 +1,10 @@
-name: Build documentation
+name: Deploy documentation and API reference
 
 on:
   # If specified, the workflow will be triggered automatically once you push to the `main` branch.
   # Replace `main` with your branch’s name
   push:
     branches: [ "main" ]
-    paths: [ "documentation/**" ]
   # Specify to run a workflow manually from the Actions tab on GitHub
   workflow_dispatch:
 
@@ -18,42 +17,43 @@ env:
   # Name of module and id separated by a slash
   INSTANCE: documentation/akkurate
   # Replace HI with the ID of the instance in capital letters
-  ARTIFACT: webHelpAKKURATE2-all.zip
+  DOC_ARTIFACT: webHelpAKKURATE2-all.zip
   # Writerside docker image version
   DOCKER_VERSION: 2.1.1479-p3869
   # Add the variable below to upload Algolia indexes
   # Replace HI with the ID of the instance in capital letters
   ALGOLIA_ARTIFACT: algolia-indexes-AKKURATE.zip
 
 jobs:
-  build:
+  build-documentation:
+    name: Build documentation
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
 
-      - name: Build Writerside docs using Docker
+      - name: Build documentation
         uses: JetBrains/writerside-github-action@v4
         with:
           instance: ${{ env.INSTANCE }}
-          artifact: ${{ env.ARTIFACT }}
+          artifact: ${{ env.DOC_ARTIFACT }}
           docker-version: ${{ env.DOCKER_VERSION }}
 
       - name: Upload documentation
         uses: actions/upload-artifact@v3
         with:
           name: docs
           path: |
-            artifacts/${{ env.ARTIFACT }}
-            artifacts/report.json
+            ./artifacts/${{ env.DOC_ARTIFACT }}
+            ./artifacts/report.json
           retention-days: 7
 
       - name: Upload social image
         uses: actions/upload-artifact@v3
         with:
           name: social-image
-          path: documentation/images/social.png
+          path: ./documentation/images/social.png
           retention-days: 7
 
       # Add the step below to upload Algolia indexes
@@ -64,10 +64,40 @@ jobs:
   #          path: artifacts/${{ env.ALGOLIA_ARTIFACT }}
   #          retention-days: 7
 
+  build-api-reference:
+    name: Build API reference
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v3
+        with:
+          java-version: 17
+          distribution: zulu
+
+      - name: Validate Gradle wrapper
+        uses: gradle/wrapper-validation-action@ccb4328a959376b642e027874838f60f8e596de3
+
+      - name: Build with Gradle
+        uses: gradle/gradle-build-action@749f47bda3e44aa060e82d7b3ef7e40d953bd629
+        with:
+          arguments: dokkaHtmlMultiModule
+
+      - name: Upload API reference
+        uses: actions/upload-artifact@v3
+        with:
+          name: api
+          path: ./build/dokka/htmlMultiModule/
+          retention-days: 7
+
   # Add the job below and artifacts/report.json on Upload documentation step above if you want to fail the build when documentation contains errors
-  test:
+  test-documentation:
+    name: Test documentation
     # Requires build job results
-    needs: build
+    needs: build-documentation
     runs-on: ubuntu-latest
 
     steps:
@@ -83,36 +113,41 @@ jobs:
           instance: ${{ env.INSTANCE }}
 
   deploy:
+    name: Deploy everything
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     # Requires the build job results
-    needs: test
+    needs: [ test-documentation, build-api-reference ]
     runs-on: ubuntu-latest
     steps:
       - name: Download documentation
         uses: actions/download-artifact@v3
         with:
           name: docs
 
-      - run: unzip -qq ${{ env.ARTIFACT }} -d dir
+      - name: Unzip documentation
+        run: mkdir website && unzip -qq ${{ env.DOC_ARTIFACT }} -d website/docs
 
-      - run: ls -l .
-      - run: ls -l dir
+      - name: Download API reference
+        uses: actions/download-artifact@v3
+        with:
+          name: api
+          path: ./website/api/
 
       - name: Download social image
         uses: actions/download-artifact@v3
         with:
           name: social-image
-          path: dir
+          path: ./website/
 
       - name: Setup Pages
         uses: actions/configure-pages@v2
 
       - name: Upload Pages contents
         uses: actions/upload-pages-artifact@v1
         with:
-          path: dir
+          path: website
 
       - name: Deploy to GitHub Pages
         id: deployment

documentation/topics/apply-constraints.md

@@ -11,7 +11,7 @@ without having to write custom constraints for anything else than business logic
 > This is a bold assertion and, let's be honest, it might not be true at the moment. _But we want it to be true!_ So let
 > us know if you're missing a constraint, [and report it on our GitHub repository.](%github_product_url%/issues)
 
-[Find all the documented constraints in the API reference.](%api_reference_url%)
+[Find all the documented constraints in the API reference.](%api_reference_url%/akkurate-core/dev.nesk.akkurate.constraints.builders/index.html)
 
 ## Basic usage
 

documentation/v.list

@@ -4,5 +4,5 @@
     <var name="product" value="Akkurate"/>
     <var name="version" value="0.1.0"/>
     <var name="github_product_url" value="https://github.com/nesk/akkurate"/>
-    <var name="api_reference_url" value="https://example.com/"/>
+    <var name="api_reference_url" value="https://akkurate.dev/api"/>
 </vars>

documentation/writerside.cfg

@@ -3,6 +3,6 @@
 
 <ihp version="2.0">
     <topics dir="topics"/>
-    <images dir="images"/>
+    <images dir="images" web-path="images"/>
     <instance src="akkurate.tree" version="0.1.0"/>
 </ihp>