Merge pull request #173 from pedestal/hls/antora

Setup for Antora documentation generation

.github/workflows/ci.yml

@@ -3,15 +3,6 @@ on:
   push:
     branches:
       - master
-
-# See https://iocanel.com/2021/09/using-sdkman-in-github-actions/
-
-# We need to set these defaults so that .bashrc is called for each step.
-# This is needed so that sdkman can be properly intialized
-defaults:
-  run:
-    shell: bash -ieo pipefail {0}
-
 env:
   UPLOAD_BUCKET: s3://pedestal.io-upload
   DEPLOY_BUCKET: s3://pedestal.io
@@ -21,41 +12,35 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set AWS credentials
-        uses: aws-actions/configure-aws-credentials@v1
+        uses: aws-actions/configure-aws-credentials@v4.0.1
         with:
           aws-access-key-id: ${{ secrets.DOCS_AWS_ACCESS_KEY_ID }}
           aws-secret-access-key: ${{ secrets.DOCS_AWS_ACCESS_KEY }}
           aws-region: us-east-1
       - name: Checkout
-        uses: actions/checkout@v3.4.0
-      - name: Setup Java
-        uses: actions/setup-java@v3.10.0
+        uses: actions/checkout@v4.1.1
+      # TODO: Cache Dependencies
+      - name: Install Node.js
+        uses: actions/setup-node@v3
         with:
-          java-version: '17'
-          distribution: 'corretto'
-      - name: Setup Sdkman
-        run: |
-          curl -s "https://get.sdkman.io" | bash
-          source "$HOME/.sdkman/bin/sdkman-init.sh"
-          sdkman_auto_answer=false
-          sdkman_selfupdate_enable=false
-      - name: Setup JBake
+          node-version: '20'          
+      - name: Install Antora
         run: |
-          sdk install jbake 2.6.7
-      - name: Run JBake
-        run: jbake -b
-      - name: Copy API docs
-        run: cp -r api output
+          npm install --save-dev --save-exact  # Uses package.json, package-lock.json
+          npx antora -v
+      - name: Run Antora
+        # --fetch forces a fetch even if the repo previously exists
+        run: npx antora --fetch antora-playbook.yml
       - name: Upload to AWS
-        # Clear the upload bucket, then copy files with extensions normally,
-        # then copy files with no extension (presumed to be HTML).
-        # Copies to a temporary bucket
+        # Clear the upload bucket, then copy files to the it.
         run: |
-          aws s3 rm ${{ env.UPLOAD_BUCKET }} 
-          aws s3 cp output/ ${{ env.UPLOAD_BUCKET }} --recursive --exclude "*" --include "*.[a-z]*"
-          aws s3 cp output/ ${{ env.UPLOAD_BUCKET }} --recursive --include "*" --exclude "*.[a-z]*" --content-type text/html
+          aws s3 rm ${{ env.UPLOAD_BUCKET }} --recursive
+          aws s3 cp api ${{ env.UPLOAD_BUCKET }}/api --recursive
+          aws s3 cp build/site ${{ env.UPLOAD_BUCKET }} --recursive
           aws s3 cp script/robots.txt ${{ env.UPLOAD_BUCKET }}
+          aws s3 ls ${{ env.UPLOAD_BUCKET }}  # Temporary!
         # Sync the temporary bucket to the real bucket (should be super fast).
         # Goal here was to minimize disruption when rolling out changes.
+      # Temporarily copy to the /antora directory (until docs are ready to go)
       - name: Sync upload to deployed
-        run: aws s3 sync ${{ env.UPLOAD_BUCKET }} ${{ env.DEPLOY_BUCKET }} --delete
+        run: aws s3 sync ${{ env.UPLOAD_BUCKET }} ${{ env.DEPLOY_BUCKET }}/antora --delete

.gitignore

@@ -1,12 +1,15 @@
-# JBake ignores
-output/*
+# Antora
+
+build/*
+package-lock.json
+
+node_modules/
 
 # Leiningen ignores
 pom.xml
 pom.xml.asc
 *.jar
 *.class
-/lib/
 /classes/
 /target/
 /checkouts/

README.md

@@ -1,4 +1,4 @@
-# Pedestal Docs [![Build Status](https://travis-ci.com/pedestal/pedestal-docs.svg?branch=master)](https://travis-ci.com/pedestal/pedestal-docs)
+# Pedestal Docs [![CI](https://github.com/pedestal/pedestal-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/pedestal/pedestal-docs/actions/workflows/ci.yml)
 
 This is an open-source repository of documentation for the
 [Pedestal](https://github.com/pedestal/pedestal) libraries.
@@ -11,40 +11,39 @@ This is an open-source repository of documentation for the
 
 If you wish to point out an issue in the site or propose a new page,
 you can do so by filing a GitHub issue at
-https://github.com/pedestal/pedestal-docs/issues
+https://github.com/pedestal/pedestal/issues
 
 If you wish to make a contribution (typo, modification, or new
 content), see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-## Building the Site
-
-The site is built using [JBake](http://jbake.org/).
-
-See the JBake [download](https://jbake.org/download.html) site for installation instructions.
-
-You'll need a recent version of JBake; if you are on an M1 Mac, you'll need 2.7.0 (currently pre-release).
+## Setup
 
-To build the site, you need side-by-side checkouts of Pedestal and Pedestal Docs.
+The site is built using [Antora](https://antora.org/).
 
-Retrieve Pedestal and switch to a publicly-available version:
+* You must have a recent version of [NodeJS](https://nodejs.org/)
+* You need the  [watchexec command](https://github.com/watchexec/watchexec); on OS X: `brew install watchexec`
+* Finally, a local install of Antora: `npm install` will download Antora and its dependencies
 
-    git clone https://github.com/pedestal/pedestal.git pedestal
-    cd pedestal
-    git checkout 0.5.8
-    cd .. # back out to the parent directory
+## Building the Site
 
-To build the site:
+When building locally, you will need two sibling workspaces: one for this repository, and one for the main
+Pedestal source.
 
 Retrieve the content:
 
-* `git clone https://github.com/pedestal/docs.git pedestal-docs` (or your own fork)
+* `git clone https://github.com/pedestal/pedestal-docs.git` (or your own fork)
+* `git clone https://github.com/pedestal/pedestal.git` (or your own fork)
 * `cd pedestal-docs`
+* `script/local-build.sh`
+
+Console output will identify the local file URL to load to see the generated site.
 
-Generate the pages:
+The `local-build.sh` script uses `watchexec` to monitor the `pedestal/docs` folders for changes and (almost instantly!)
+rebuild the output documentation (you'll have to manually refresh your browser). It will also generate
+desktop notifications when it runs, on supported platforms.
 
-* `jbake -b -s` - this will create the static site in the output
-  directory, start a web server and watch for changes. The local site
-  is available at http://localhost:8820/index.
+CAUTION: Working inside NuBank will screw up `package-lock.json` file, polluting it with references to NuBank's internal repository; 
+`package-lock.json` has been temporarily added to `.gitignore` until we work out a better approach.
 
 ### Pedestal API Documentation
 
@@ -54,6 +53,31 @@ the `script/gen-api-doc.sh` script.
 This generates API documentation into the `api` directory.  When deploying, the contents of
 the `api` directory are merged with the generated content in `output`.
 
+The `api` directory is tracked by Git; you should commit and push the changes to ensure that the
+official CI (Continuous Integration, via a GitHub action) build generates the `pedestal.io` site using
+the updated API documentation.
+
+NOTE: May change this to a more Antora-friendly approach soon!
+
+
+### Antora Notes
+
+On OS X, Antora stores Git repos in `~/Library/Caches/antora/` by default.
+
+Be careful to keep `antora-playbook.yml` and `local-antora-playbook.yml` in sync.
+
+We are currently using the default Antora UI, with overrides in the `ui-overrides` directory.
+
+We (at least temporarily) added `package-lock.json` to `.gitignore`, as it kept getting filled up
+with NuBank-specific URLs; this adds some risk that the environment for the GitHub action that does
+the publishing will drift from local.
+
+Some old directories from the jBake build are still present, such as `content`, `assets`,
+and `templates`.  They are being kept for reference as UI updates to the Antora-generated
+site continue.
+
+Publishing of the site is currently to http://pedestal.io/antora/pedestal/0.7-pre/index.html (note the `antora` directory), to keep the current (jBake-generated) site stable.
+
 License
 -------
 Copyright 2014-2023 Cognitect, Inc.

antora-playbook.yml

@@ -0,0 +1,19 @@
+site:
+  title: Pedestal
+  start_page: pedestal::index.adoc
+content:
+  sources:
+  - url: https://github.com/pedestal/pedestal.git
+    branches: master
+    start_path: docs
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files: ./ui-overrides
+asciidoc:
+  extensions:
+    - lib/pedestal-macros.js
+antora:
+  extensions:
+    - '@antora/lunr-extension'