Skip to content

Commit 41bf953

Browse files
WalkerWatchjoakime
WalkerWatch
and
joakime
authored
Issue #5603 - Single page documentation (#5636)
* First pass of single page doc generation for 9.4.x * Updates to POM and HTML assembly * Update snapshot version * Removing deprecated Docbook assets * Moving asciidoc config to main pom, removing sub-order references * Fixing image links * Cleaning up code reference formatting * Fixing missed source formatting * Flipping Admonitions MK. I * Replacing underscores for admonitions * Converting .... to ---- for code blocks * Reverting accidentally changed KEYS.txt Signed-off-by: Joakim Erdfelt <joakim.erdfelt@gmail.com> * Clean up * Fixing icons Co-authored-by: Joakim Erdfelt <joakim.erdfelt@gmail.com>
1 parent fcfa72e commit 41bf953

215 files changed

Lines changed: 1711 additions & 7176 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎jetty-documentation/pom.xml‎

Lines changed: 4 additions & 209 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,21 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<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">
3-
<modelVersion>4.0.0</modelVersion>
43
<parent>
54
<groupId>org.eclipse.jetty</groupId>
65
<artifactId>jetty-project</artifactId>
76
<version>9.4.35-SNAPSHOT</version>
87
</parent>
8+
9+
<modelVersion>4.0.0</modelVersion>
910
<artifactId>jetty-documentation</artifactId>
1011
<name>Jetty :: Documentation</name>
1112
<packaging>pom</packaging>
12-
<properties>
13-
<html.directory>${project.build.directory}/current</html.directory>
14-
<javadoc.version>${project.version}</javadoc.version>
15-
</properties>
13+
1614
<build>
1715
<plugins>
18-
<plugin>
19-
<artifactId>maven-resources-plugin</artifactId>
20-
<executions>
21-
<execution>
22-
<id>copy-assets</id>
23-
<phase>process-resources</phase>
24-
<goals>
25-
<goal>copy-resources</goal>
26-
</goals>
27-
<configuration>
28-
<resources>
29-
<resource>
30-
<directory>src/main/resources</directory>
31-
<includes>
32-
<include>**</include>
33-
</includes>
34-
</resource>
35-
</resources>
36-
<outputDirectory>${html.directory}</outputDirectory>
37-
</configuration>
38-
</execution>
39-
</executions>
40-
</plugin>
4116
<plugin>
4217
<groupId>org.asciidoctor</groupId>
4318
<artifactId>asciidoctor-maven-plugin</artifactId>
44-
<executions>
45-
<execution>
46-
<id>output-html</id>
47-
<phase>compile</phase>
48-
<goals>
49-
<goal>process-asciidoc</goal>
50-
</goals>
51-
<configuration>
52-
<backend>docbook</backend>
53-
<doctype>book</doctype>
54-
<sourceDocumentName>index.adoc</sourceDocumentName>
55-
<attributes>
56-
<sub-order>attributes+</sub-order>
57-
<imagesdir />
58-
<linkcss>true</linkcss>
59-
<allow-uri-read>true</allow-uri-read>
60-
<toc>true</toc>
61-
<revnumber>${project.version}</revnumber>
62-
<JDURL>https://eclipse.org/jetty/javadoc/${javadoc.version}</JDURL>
63-
<JXURL>https://download.eclipse.org/jetty/stable-9/xref</JXURL>
64-
<SRCDIR>${basedir}/..</SRCDIR>
65-
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/jetty-9.4.x</GITBROWSEURL>
66-
<MVNCENTRAL>https://repo1.maven.org/maven2</MVNCENTRAL>
67-
<VERSION>${project.version}</VERSION>
68-
</attributes>
69-
</configuration>
70-
</execution>
71-
</executions>
72-
</plugin>
73-
<plugin>
74-
<groupId>com.agilejava.docbkx</groupId>
75-
<artifactId>docbkx-maven-plugin</artifactId>
76-
<version>2.0.17</version>
77-
<executions>
78-
<execution>
79-
<id>html</id>
80-
<phase>compile</phase>
81-
<goals>
82-
<goal>generate-html</goal>
83-
</goals>
84-
<configuration>
85-
<htmlStylesheet>css/docbook.css</htmlStylesheet>
86-
<htmlCustomization>${project.basedir}/src/main/docbkx-stylesheet/html/docbook.xsl</htmlCustomization>
87-
<preProcess>
88-
<!-- pull over the images from the source material -->
89-
<copy todir="target/docbkx/html/images" flatten="true">
90-
<fileset dir="src/main/asciidoc">
91-
<include name="**/*.png" />
92-
<include name="**/*.jpg" />
93-
<include name="**/*.svg" />
94-
<include name="**/*.dot" />
95-
</fileset>
96-
</copy>
97-
<copy todir="target/docbkx/html/images">
98-
<fileset dir="src/main/docbkx-resources/images" />
99-
</copy>
100-
<copy todir="target/docbkx/html/css">
101-
<fileset dir="src/main/docbkx-resources/css" />
102-
</copy>
103-
<copy todir="target/docbkx/html/fonts">
104-
<fileset dir="src/main/docbkx-resources/fonts" />
105-
</copy>
106-
<copy todir="target/docbkx/html/js">
107-
<fileset dir="src/main/docbkx-resources/js" />
108-
</copy>
109-
</preProcess>
110-
</configuration>
111-
</execution>
112-
</executions>
113-
<configuration>
114-
<!-- shared configuration -->
115-
<sourceDirectory>${project.build.directory}/generated-docs</sourceDirectory>
116-
<includes>index.xml</includes>
117-
<generatedSourceDirectory>${project.build.directory}/docbkx/generated</generatedSourceDirectory>
118-
<chunkedOutput>true</chunkedOutput>
119-
<highlightSource>true</highlightSource>
120-
</configuration>
121-
<dependencies>
122-
<dependency>
123-
<groupId>net.sf.docbook</groupId>
124-
<artifactId>docbook-xml</artifactId>
125-
<version>5.1b4-all</version>
126-
<classifier>resources</classifier>
127-
<type>zip</type>
128-
<scope>runtime</scope>
129-
</dependency>
130-
<dependency>
131-
<groupId>net.sf.xslthl</groupId>
132-
<artifactId>xslthl</artifactId>
133-
<version>2.1.3</version>
134-
<scope>runtime</scope>
135-
</dependency>
136-
<dependency>
137-
<groupId>org.eclipse.jetty.toolchain</groupId>
138-
<artifactId>jetty-xslt-tools</artifactId>
139-
<version>1.3</version>
140-
<scope>runtime</scope>
141-
</dependency>
142-
</dependencies>
14319
</plugin>
14420
<plugin>
14521
<artifactId>maven-assembly-plugin</artifactId>
@@ -160,85 +36,4 @@
16036
</plugin>
16137
</plugins>
16238
</build>
163-
<profiles>
164-
<!--
165-
Couple of different approaches to generating pdf's
166-
-->
167-
<profile>
168-
<id>generate-pdf</id>
169-
<build>
170-
<plugins>
171-
<plugin>
172-
<groupId>com.agilejava.docbkx</groupId>
173-
<artifactId>docbkx-maven-plugin</artifactId>
174-
<executions>
175-
<execution>
176-
<id>generate-pdf</id>
177-
<phase>compile</phase>
178-
<goals>
179-
<goal>generate-pdf</goal>
180-
</goals>
181-
<configuration>
182-
<includes>index.xml</includes>
183-
<fop1Extensions>1</fop1Extensions>
184-
<paperType>A4</paperType>
185-
<foCustomization>src/main/docbkx-stylesheet/fo/docbook.xsl</foCustomization>
186-
</configuration>
187-
</execution>
188-
</executions>
189-
<dependencies>
190-
<dependency>
191-
<groupId>net.sf.offo</groupId>
192-
<artifactId>fop-hyph</artifactId>
193-
<version>1.2</version>
194-
<scope>runtime</scope>
195-
</dependency>
196-
</dependencies>
197-
</plugin>
198-
<plugin>
199-
<groupId>org.asciidoctor</groupId>
200-
<artifactId>asciidoctor-maven-plugin</artifactId>
201-
<dependencies>
202-
<dependency>
203-
<groupId>org.asciidoctor</groupId>
204-
<artifactId>asciidoctorj-pdf</artifactId>
205-
<version>1.5.0-alpha.11</version>
206-
</dependency>
207-
</dependencies>
208-
<executions>
209-
<execution>
210-
<id>output-pdf</id>
211-
<phase>generate-sources</phase>
212-
<goals>
213-
<goal>process-asciidoc</goal>
214-
</goals>
215-
<configuration>
216-
<backend>pdf</backend>
217-
<sourceHighlighter>rouge</sourceHighlighter>
218-
<sourceDocumentName>index.adoc</sourceDocumentName>
219-
<attributes>
220-
<imagesdir />
221-
<version>${project.version}</version>
222-
<linkcss>true</linkcss>
223-
<allow-uri-read>true</allow-uri-read>
224-
<toc>true</toc>
225-
<revnumber>${project.version}</revnumber>
226-
<JDURL>https://download.eclipse.org/jetty/stable-9/apidocs</JDURL>
227-
<JXURL>https://download.eclipse.org/jetty/stable-9/xref</JXURL>
228-
<SRCDIR>${basedir}/../jetty.project/</SRCDIR>
229-
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/jetty-9.4.x</GITBROWSEURL>
230-
<icons>font</icons>
231-
<pagenums />
232-
<toc />
233-
<idprefix />
234-
<idseparator>-</idseparator>
235-
</attributes>
236-
</configuration>
237-
</execution>
238-
</executions>
239-
</plugin>
240-
</plugins>
241-
</build>
242-
</profile>
243-
</profiles>
244-
</project>
39+
</project>

‎jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc‎

Lines changed: 20 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -90,19 +90,18 @@ or alternatively you need the link:#alpn-openjdk8-agent[Jetty ALPN agent].
9090

9191
In the case of the Jetty ALPN boot library, start the JVM as follows:
9292

93-
[source, plain, subs="{sub-order}"]
93+
[source, plain]
9494
----
9595
java -Xbootclasspath/p:<path_to_alpn_boot_jar> ...
9696
----
9797

9898
Where `path_to_alpn_boot_jar` is the path on the file system for the `alpn-boot` artifact, such as the one at the Maven coordinates `org.mortbay.jetty.alpn:alpn-boot`.
9999

100-
____
101100
[IMPORTANT]
101+
====
102102
Be certain to get the
103103
link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE].
104-
____
105-
104+
====
106105
[[alpn-openjdk8-agent]]
107106
==== ALPN agent and OpenJDK 8
108107

@@ -121,22 +120,21 @@ transforms, if necessary, the relevant OpenJDK classes to provide the ALPN suppo
121120

122121
To use the Jetty ALPN agent, start the JVM as follows:
123122

124-
[source, plain, subs="{sub-order}"]
123+
[source, plain]
125124
----
126125
java -javaagent:<path_to_alpn_agent_jar> ...
127126
----
128127

129-
____
130128
[NOTE]
129+
====
131130
The Jetty ALPN agent works with any Java 8 version. It is _required_ if you use
132131
an OpenJDK version up to `1.8.0_242` included, and it is _optional_ if you use an
133132
OpenJDK version equal or greater than `1.8.0_252`.
134133
135134
The Jetty ALPN agent can be left on the command line even when using an OpenJDK version
136135
equal or greater than `1.8.0_252` but we recommend to remove it from the command line
137136
when you use OpenJDK `1.8.0_252` or later.
138-
____
139-
137+
====
140138
[[alpn-conscrypt]]
141139
==== ALPN and Conscrypt
142140

@@ -166,19 +164,18 @@ This jar contains a `Fragment-Host` directive that ensures the ALPN classes will
166164

167165
You can download the https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-alpn/[jetty-osgi-alpn jar] from Maven Central.
168166

169-
____
170167
[NOTE]
168+
====
171169
OSGi *requires* a `ServiceLoader` implementation for Jetty to function properly.
172170
OSGi leverages http://aries.apache.org/modules/spi-fly.html[Apache Aries SPI Fly] for this functionality.
173171
You can read more about OSGi and `ServiceLoader` http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html[here.]
174-
____
175-
172+
====
176173
[[alpn-troubleshooting]]
177174
==== ALPN Troubleshooting
178175

179176
When starting the Jetty server, especially when using Jetty embedded, it may be possible that you see an error similar to this:
180177

181-
[source, plain, subs="{sub-order}"]
178+
[source, plain]
182179
----
183180
IllegalStateException: no ALPN processor
184181
----
@@ -217,7 +214,7 @@ Refer to `ALPN` Javadocs and to the examples below for further details about cli
217214
[[alpn-openjdk8-client-example]]
218215
==== Client Example
219216

220-
[source, java, subs="{sub-order}"]
217+
[source, java]
221218
----
222219
SSLContext sslContext = ...;
223220
SSLSocket sslSocket = (SSLSocket)context.getSocketFactory().createSocket("localhost", server.getLocalPort());
@@ -257,7 +254,7 @@ The ALPN implementation calls `ALPN.ClientProvider` methods `protocols()`, `unsu
257254

258255
The example for `SSLEngine` is identical, and you just need to replace the `SSLSocket` instance with an `SSLEngine` instance.
259256

260-
[source, java, subs="{sub-order}"]
257+
[source, java]
261258
----
262259
SSLEngine sslEngine = ...;
263260
ALPN.put(sslEngine, new ALPN.ServerProvider()
@@ -294,7 +291,7 @@ Failing to do so will cause a memory leak.
294291
You can write and run unit tests that use the ALPN implementation.
295292
The solution that we use with Maven is to specify an additional command line argument to the Surefire plugin:
296293

297-
[source, xml, subs="{sub-order}"]
294+
[source, xml]
298295
----
299296
<project>
300297
@@ -328,9 +325,9 @@ The solution that we use with Maven is to specify an additional command line arg
328325

329326
You can enable debug logging for the ALPN implementation in this way:
330327

331-
....
328+
----
332329
ALPN.debug = true;
333-
....
330+
----
334331

335332
Since the ALPN class is in the boot classpath, we chose not to use logging libraries because we do not want to override application logging library choices; therefore the logging is performed directly on `System.err`.
336333

@@ -427,20 +424,20 @@ This section is for Jetty developers that need to update the ALPN implementation
427424

428425
Clone the OpenJDK repository with the following command:
429426

430-
[source, screen, subs="{sub-order}"]
431-
....
427+
[source, screen]
428+
----
432429
$ hg clone https://hg.openjdk.java.net/jdk8u/jdk8u jdk8u
433430
$ cd !$
434431
$ ./get_source.sh
435-
....
432+
----
436433

437434
To update the source to a specific tag, use the following command:
438435

439-
[source, screen, subs="{sub-order}"]
440-
....
436+
[source, screen]
437+
----
441438
$ ./make/scripts/hgforest.sh update <tag-name>
442439
443-
....
440+
----
444441

445442
The list of OpenJDK tags can be obtained from this page:
446443
https://hg.openjdk.java.net/jdk8u/jdk8u/tags[OpenJDK 8 Tags].

‎jetty-documentation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ Below is an example application that sets up the standard `test-spec.war` webapp
3939
It can also be found in the Jetty GitHub repository on the examples/embedded page as link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded[`ServerWithAnnotations.java`.]
4040
Note that the `test-spec.war` uses not only annotations, but also link:#jndi[JNDI], so this example also enables their processing (via the link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.EnvConfiguration], link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.PlusConfiguration] and their related jars).
4141

42-
[source, java, subs="{sub-order}"]
42+
[source, java]
4343
----
4444
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ServerWithAnnotations.java[]
4545
----

0 commit comments

Comments
 (0)