migrate documentation to Antora

jetty · May 20, 2024 · 239636d · 239636d
1 parent a4c2970
commit 239636d
Show file tree

Hide file tree

Showing 95 changed files with 27,364 additions and 2 deletions.
diff --git a/documentation/jetty/.gitignore b/documentation/jetty/.gitignore
@@ -0,0 +1,2 @@
+/.asciidoctorconfig
+/provided-antora-playbook.yml
diff --git a/documentation/jetty/README.adoc b/documentation/jetty/README.adoc
@@ -0,0 +1,32 @@
+//
+// ========================================================================
+// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+= Jetty Documentation
+
+This project is the root of the Jetty documentation.
+The content files in this project get sourced by the Antora playbook in the playbook repository that builds the website.
+
+In order to build the documentation locally, you first need to prepare a jetty-home directory by running the following command from the top-level folder of the Jetty project:
+
+ $ mvn install -Dcollector -Pfast -am -pl documentation/jetty
+
+Then you can use the following command from this directory to prepare and run Antora using a preview profile:
+
+ $ mvn antora -N
+
+If you don't run the first command, the Antora build will still succeed, but you will get warnings about missing includes for files taken from jetty-home.
+
+The `antora:antora` goal, which the `antora` lifecycle invokes, takes advantage of the playbook provider feature so the playbook for this branch can be centrally managed in the playbook repository.
+
+Note that this preview profile does not run the jetty blocks, so you will only see the configuration for those runs in the preview site.
+If you want to build the full site, use the build in the playbook repository.
diff --git a/documentation/jetty/antora.yml b/documentation/jetty/antora.yml
@@ -0,0 +1,28 @@
+name: jetty
+version: '12'
+title: Eclipse Jetty
+asciidoc:
+  attributes:
+    javadoc-url: https://eclipse.dev/jetty/javadoc/jetty-12
+    jdurl: '{javadoc-url}'
+    jetty-home: ${jetty.home}@
+    version: 12.0.10-SNAPSHOT
+    idprefix: ''
+    idseparator: ''
+    ee-all: ee{8,9,10}
+    ee-current: ee10
+    ee-current-caps: EE 10
+    run-jetty-classpath: ${settings.localRepository}/org/eclipse/jetty/tests/jetty-testers/${project.version}/jetty-testers-${project.version}.jar${path.separator}${run.jetty.classpath}
+nav:
+- modules/operations-guide/nav.adoc
+- modules/programming-guide/nav.adoc
+ext:
+  collector:
+  - run:
+      command: mvn install -ntp -B -Dcollector -Pfast -am -pl documentation/jetty
+    scan:
+      dir: documentation/jetty/target/collector
+  - scan:
+      dir: jetty-core/jetty-server/src/main/java
+      files: org/eclipse/jetty/server/CustomRequestLog.java
+      base: modules/code/partials
diff --git a/documentation/jetty/modules/ROOT/pages/index.adoc b/documentation/jetty/modules/ROOT/pages/index.adoc
@@ -0,0 +1,24 @@
+//
+// ========================================================================
+// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+= Eclipse Jetty
+
+This section of the site contains the documentation for {page-component-title} {page-version}.
+
+== xref:operations-guide:index.adoc[]
+
+The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
+
+== xref:programming-guide:index.adoc[]
+
+The Eclipse Jetty Programming Guide targets developers who want to use the Eclipse Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.
diff --git a/documentation/jetty/modules/code/examples/jetty-modules/jpms.mod b/documentation/jetty/modules/code/examples/jetty-modules/jpms.mod
@@ -0,0 +1,8 @@
+[description]
+JPMS Configuration Module
+
+[ini]
+--jpms
+
+[jpms]
+# Additional JPMS configuration.
diff --git a/documentation/jetty/modules/code/examples/jetty-modules/jvm.mod b/documentation/jetty/modules/code/examples/jetty-modules/jvm.mod
@@ -0,0 +1,6 @@
+[description]
+JVM Options Module
+
+[exec]
+-Xmx1g
+-Xlog:gc*,gc+stats=off:file=logs/gc.log:time,level,tags
diff --git a/documentation/jetty/modules/code/examples/jetty-modules/postgresql.mod b/documentation/jetty/modules/code/examples/jetty-modules/postgresql.mod
@@ -0,0 +1,15 @@
+[description]
+Postgres JDBC Driver Module
+
+[lib]
+lib/postgresql-${postgresql-version}.jar
+
+[files]
+maven://org.postgresql/postgresql/${postgresql-version}|lib/postgresql-${postgresql-version}.jar
+
+[ini]
+postgresql-version?=42.6.0
+
+[ini-template]
+## Postgres JDBC version.
+# postgresql-version=42.6.0
diff --git a/documentation/jetty/modules/code/examples/jetty-modules/remote-debug.mod b/documentation/jetty/modules/code/examples/jetty-modules/remote-debug.mod
@@ -0,0 +1,5 @@
+[description]
+Enables remote debugging
+
+[exec]
+-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
diff --git a/documentation/jetty/modules/code/examples/pom.xml b/documentation/jetty/modules/code/examples/pom.xml
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.eclipse.jetty.documentation</groupId>
+    <artifactId>documentation</artifactId>
+    <version>12.0.10-SNAPSHOT</version>
+    <relativePath>../../../../pom.xml</relativePath>
+  </parent>
+  <artifactId>code-examples</artifactId>
+  <packaging>pom</packaging>
+  <name>Documentation :: Code Examples</name>
+
+  <properties>
+    <jacoco.skip>true</jacoco.skip>
+    <javadoc.skip>true</javadoc.skip>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-alpn-server</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-infinispan-embedded-query</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-infinispan-remote-query</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-jmx</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-nosql</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-rewrite</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-server</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-session</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-unixdomain-server</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty</groupId>
+      <artifactId>jetty-util-ajax</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.ee10</groupId>
+      <artifactId>jetty-ee10-servlet</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.ee10</groupId>
+      <artifactId>jetty-ee10-servlets</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.ee10.websocket</groupId>
+      <artifactId>jetty-ee10-websocket-jakarta-server</artifactId>
+      <version>${project.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.fcgi</groupId>
+      <artifactId>jetty-fcgi-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.gcloud</groupId>
+      <artifactId>jetty-gcloud-session-manager</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.http2</groupId>
+      <artifactId>jetty-http2-client-transport</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.http2</groupId>
+      <artifactId>jetty-http2-server</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.http3</groupId>
+      <artifactId>jetty-http3-client-transport</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.http3</groupId>
+      <artifactId>jetty-http3-server</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.memcached</groupId>
+      <artifactId>jetty-memcached-sessions</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.websocket</groupId>
+      <artifactId>jetty-websocket-jetty-client</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jetty.websocket</groupId>
+      <artifactId>jetty-websocket-jetty-server</artifactId>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>compile-code-examples</id>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <phase>compile</phase>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-enforcer-plugin</artifactId>
+        <configuration>
+          <fail>false</fail>
+          <rules>
+            <requireJavaVersion>
+              <version>[21,)</version>
+              <message>[ERROR] OLD JDK [${java.version}] in use. Jetty documentation ${project.version} MUST use JDK 21 or newer</message>
+            </requireJavaVersion>
+          </rules>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+  <profiles>
+    <profile>
+      <id>jdk17-18</id>
+      <activation>
+        <jdk>[17,19)</jdk>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+              <excludes>
+                <exclude>**/ArchitectureDocs.java</exclude>
+              </excludes>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+    <profile>
+      <id>jdk19-20</id>
+      <activation>
+        <jdk>[19,21)</jdk>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+              <source>${java.specification.version}</source>
+              <target>${java.specification.version}</target>
+              <release>${java.specification.version}</release>
+              <enablePreview>true</enablePreview>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+    <profile>
+      <id>jdk21+</id>
+      <activation>
+        <jdk>[21,)</jdk>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <artifactId>maven-compiler-plugin</artifactId>
+            <configuration>
+              <source>${java.specification.version}</source>
+              <target>${java.specification.version}</target>
+              <release>${java.specification.version}</release>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
+</project>
diff --git a/...ules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/ArchitectureDocs.java b/...ules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/ArchitectureDocs.java
@@ -0,0 +1,33 @@
+//
+// ========================================================================
+// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+package org.eclipse.jetty.docs.programming;
+
+import java.util.concurrent.Executors;
+
+import org.eclipse.jetty.server.Server;
+import org.eclipse.jetty.util.thread.QueuedThreadPool;
+
+@SuppressWarnings("unused")
+public class ArchitectureDocs
+{
+    public void configureVirtualThreads()
+    {
+        // tag::virtual[]
+        QueuedThreadPool threadPool = new QueuedThreadPool();
+        threadPool.setVirtualThreadsExecutor(Executors.newVirtualThreadPerTaskExecutor());
+
+        Server server = new Server(threadPool);
+        // end::virtual[]
+    }
+}