Merge branch 'main' of github.com:webtide/jetty.website into main

.github/workflows/publish-site.yml

@@ -33,23 +33,13 @@ jobs:
       with:
         distribution: temurin
         java-version: '21'
-    - name: Install Maven
-      uses: stCarolas/setup-maven@v5
-      with:
-        maven-version: 3.9.6
-    - name: Cache Maven repository
-      uses: actions/cache@v4
-      with:
-        path: ~/.m2
-        key: ${{ runner.os }}-maven-${{ hashFiles('antora-playbook.yml') }}
-        restore-keys: |
-          ${{ runner.os }}-maven-
+        cache: maven
     - name: Generate Site
       env:
         # must set ANTORA_CACHE_DIR so Maven will put jetty home where Antora Collector won't delete it
         ANTORA_CACHE_DIR: ${{ github.workspace }}/.cache/antora
         npm_config_audit: false
-      run: mvn -B -e -V -ntp -Dorg.slf4j.simpleLogger.showDateTime=true -Dorg.slf4j.simpleLogger.dateTimeFormat=HH:mm:ss antora:antora@full
+      run: ./mvnw -B -e -V -ntp -Dorg.slf4j.simpleLogger.showDateTime=true -Dorg.slf4j.simpleLogger.dateTimeFormat=HH:mm:ss antora:antora@full
     - name: Upload Artifact
       uses: actions/upload-pages-artifact@v3
       with:

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,18 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+wrapperVersion=3.3.1
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip

README.adoc

@@ -26,6 +26,10 @@ To build the site quickly, use:
 
 Antora will print the location of the generated site in the Maven log.
 
+To ensure everyone is using the same environment, you may want to use the Maven wrapper, `mvnw` to invoke Maven instead:
+
+ $ ./mvnw antora
+
 On the first run, this command will set up Node.js (in [.path]_target/node_) and install the project dependencies (npm packages) (into [.path]_node_modules_).
 
 [NOTE]

antora-playbook.yml

@@ -9,6 +9,11 @@ antora:
   - id: register-asciidoctor-kroki
     require: ./lib/register-asciidoctor-kroki-extension.js
     enabled: false
+runtime:
+  log:
+    destination:
+      append: false
+    level: info
 site:
   title: Eclipse Jetty
   url: https://jetty.org
@@ -30,6 +35,7 @@ asciidoc:
     page-pagination: ''
   extensions:
   - ./lib/feed-block-macro.js
+  - ./lib/javadoc-block-macro.js
   - ./lib/jetty-block.js
   - ./lib/skip-include-processor.js
   - ./lib/absolute-path-include-processor.js

lib/javadoc-block-macro.js

@@ -0,0 +1,53 @@
+'use strict'
+
+const toHash = (object) => object && !object.$$is_hash ? Opal.hash2(Object.keys(object), object) : object
+
+const toProc = (fn) => Object.defineProperty(fn, '$$arity', { value: fn.length })
+
+function register (registry, context = {}) {
+  if (!(registry && context)) return // NOTE only works as scoped extension
+  registry.$groups().$store('javadoc', toProc(createExtensionGroup(context)))
+  return registry
+}
+
+function createExtensionGroup ({ contentCatalog, file }) {
+  return function () {
+    this.blockMacro('javadoc', function () {
+      this.process((parent, target, attrs) => {
+        const doc = parent.getDocument()
+        const cursor = doc.getReader().$cursor_at_mark()
+        const ctx = (cursor.file || {}).src || file.src
+        const includeFile = contentCatalog.resolveResource(target, ctx, undefined, ['partial'])
+        if (!includeFile) return this.createParagraph(parent, `javadoc::${target}[]`, {})
+        const rawLines = includeFile.contents.toString().split('\n')
+        const lines = []
+        let capturing
+        for (let line of rawLines) {
+          if (capturing) {
+            if (line.endsWith('<!-- end::documentation[] -->')) break
+            line = line.replace(/^ +[*](?: +|$)/, '')
+            if (line === '<table>') {
+              line = '<table class="tableblock frame-all grid-all stretch">'
+            } else if (line === '<dl>') {
+              lines.push('<div class="dlist">')
+            } else if (line === '</dl>') {
+              lines.push(line)
+              line = '</div>'
+            } else if (line.startsWith('<p') && !lines.length) {
+              line = '<div class="paragraph">\n' + line + '\n</div>'
+            } else if (line.startsWith('<!--')) {
+              continue
+            }
+            lines.push(line)
+          } else if (line.endsWith('<!-- tag::documentation[] -->')) {
+            capturing = true
+            continue
+          }
+        }
+        return this.createPassBlock(parent, lines, {})
+      })
+    })
+  }
+}
+
+module.exports = { register, createExtensionGroup }

lib/jetty-block.js

@@ -81,6 +81,7 @@ function createExtensionGroup (context) {
           const includeContents = execFileSync('java', args, { stdio: 'pipe', windowsHide: true }).toString().trim()
           if (includeContents) {
             if (includeContents.startsWith('**')) attrs.subs = '+quotes'
+            doc.setAttribute('run-jetty')
             return this.createBlock(parent, 'literal', includeContents, attrs)
           } else {
             log(doc, 'error', `${mainClass} no output`, cursor)

lib/skip-include-processor.js

@@ -1,15 +1,15 @@
 'use strict'
 
 /**
- * A temporary include processor to silence javadoc and $JETTY_HOME includes.
+ * An include processor to silence $JETTY_HOME includes for quick builds.
  */
 function createExtensionGroup (registry) {
   return function () {
     this.includeProcessor(function () {
       let directive
       this.prefer() // register in front of Antora's include processor
       this.handles((target) => {
-        if (target !== 'javadoc' && !target.startsWith('${jetty.home}')) return
+        if (!target.startsWith('${jetty.home}')) return
         directive = registry.document.getReader().getLines()[0]
         return true
       })