Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Issue #5603 - Single page documentation #5636

Merged
merged 15 commits into from Nov 20, 2020
Merged

Issue #5603 - Single page documentation #5636

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
110a22c
First pass of single page doc generation for 9.4.x
Nov 9, 2020
6914b49
Updates to POM and HTML assembly
Nov 9, 2020
951b74c
Update snapshot version
Nov 10, 2020
a4c612d
Removing deprecated Docbook assets
Nov 11, 2020
e543191
Moving asciidoc config to main pom, removing sub-order references
Nov 16, 2020
72e90b0
Fixing image links
Nov 16, 2020
b0b4265
Cleaning up code reference formatting
Nov 17, 2020
0fb2cfa
Fixing missed source formatting
Nov 20, 2020
f8e3c87
Flipping Admonitions MK. I
Nov 20, 2020
8daf805
Replacing underscores for admonitions
Nov 20, 2020
a31b475
Converting .... to ---- for code blocks
Nov 20, 2020
a720776
Reverting accidentally changed KEYS.txt
joakime Nov 20, 2020
10fcf04
Clean up
Nov 20, 2020
2bbcafa
Merge branch '9.4.x-5603-SinglePageDoc' of github.com:eclipse/jetty.p…
Nov 20, 2020
faf0c07
Fixing icons
Nov 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
213 changes: 4 additions & 209 deletions jetty-documentation/pom.xml
View file
Open in desktop
@@ -1,145 +1,21 @@
<?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</groupId>
<artifactId>jetty-project</artifactId>
<version>9.4.35-SNAPSHOT</version>
</parent>

<modelVersion>4.0.0</modelVersion>
<artifactId>jetty-documentation</artifactId>
<name>Jetty :: Documentation</name>
<packaging>pom</packaging>
<properties>
<html.directory>${project.build.directory}/current</html.directory>
<javadoc.version>${project.version}</javadoc.version>
</properties>

<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-assets</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>src/main/resources</directory>
<includes>
<include>**</include>
</includes>
</resource>
</resources>
<outputDirectory>${html.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>output-html</id>
<phase>compile</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>docbook</backend>
<doctype>book</doctype>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<sub-order>attributes+</sub-order>
<imagesdir />
<linkcss>true</linkcss>
<allow-uri-read>true</allow-uri-read>
<toc>true</toc>
<revnumber>${project.version}</revnumber>
<JDURL>https://eclipse.org/jetty/javadoc/${javadoc.version}</JDURL>
<JXURL>https://download.eclipse.org/jetty/stable-9/xref</JXURL>
<SRCDIR>${basedir}/..</SRCDIR>
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/jetty-9.4.x</GITBROWSEURL>
<MVNCENTRAL>https://repo1.maven.org/maven2</MVNCENTRAL>
<VERSION>${project.version}</VERSION>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.17</version>
<executions>
<execution>
<id>html</id>
<phase>compile</phase>
<goals>
<goal>generate-html</goal>
</goals>
<configuration>
<htmlStylesheet>css/docbook.css</htmlStylesheet>
<htmlCustomization>${project.basedir}/src/main/docbkx-stylesheet/html/docbook.xsl</htmlCustomization>
<preProcess>
<!-- pull over the images from the source material -->
<copy todir="target/docbkx/html/images" flatten="true">
<fileset dir="src/main/asciidoc">
<include name="**/*.png" />
<include name="**/*.jpg" />
<include name="**/*.svg" />
<include name="**/*.dot" />
</fileset>
</copy>
<copy todir="target/docbkx/html/images">
<fileset dir="src/main/docbkx-resources/images" />
</copy>
<copy todir="target/docbkx/html/css">
<fileset dir="src/main/docbkx-resources/css" />
</copy>
<copy todir="target/docbkx/html/fonts">
<fileset dir="src/main/docbkx-resources/fonts" />
</copy>
<copy todir="target/docbkx/html/js">
<fileset dir="src/main/docbkx-resources/js" />
</copy>
</preProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- shared configuration -->
<sourceDirectory>${project.build.directory}/generated-docs</sourceDirectory>
<includes>index.xml</includes>
<generatedSourceDirectory>${project.build.directory}/docbkx/generated</generatedSourceDirectory>
<chunkedOutput>true</chunkedOutput>
<highlightSource>true</highlightSource>
</configuration>
<dependencies>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.1b4-all</version>
<classifier>resources</classifier>
<type>zip</type>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>net.sf.xslthl</groupId>
<artifactId>xslthl</artifactId>
<version>2.1.3</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.toolchain</groupId>
<artifactId>jetty-xslt-tools</artifactId>
<version>1.3</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</plugin>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
Expand All @@ -160,85 +36,4 @@
</plugin>
</plugins>
</build>
<profiles>
<!--
Couple of different approaches to generating pdf's
-->
<profile>
<id>generate-pdf</id>
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-pdf</id>
<phase>compile</phase>
<goals>
<goal>generate-pdf</goal>
</goals>
<configuration>
<includes>index.xml</includes>
<fop1Extensions>1</fop1Extensions>
<paperType>A4</paperType>
<foCustomization>src/main/docbkx-stylesheet/fo/docbook.xsl</foCustomization>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>net.sf.offo</groupId>
<artifactId>fop-hyph</artifactId>
<version>1.2</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>output-pdf</id>
<phase>generate-sources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceHighlighter>rouge</sourceHighlighter>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<imagesdir />
<version>${project.version}</version>
<linkcss>true</linkcss>
<allow-uri-read>true</allow-uri-read>
<toc>true</toc>
<revnumber>${project.version}</revnumber>
<JDURL>https://download.eclipse.org/jetty/stable-9/apidocs</JDURL>
<JXURL>https://download.eclipse.org/jetty/stable-9/xref</JXURL>
<SRCDIR>${basedir}/../jetty.project/</SRCDIR>
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/jetty-9.4.x</GITBROWSEURL>
<icons>font</icons>
<pagenums />
<toc />
<idprefix />
<idseparator>-</idseparator>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
</project>
43 changes: 20 additions & 23 deletions jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
View file
Open in desktop
Expand Up @@ -90,19 +90,18 @@ or alternatively you need the link:#alpn-openjdk8-agent[Jetty ALPN agent].

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

[source, plain, subs="{sub-order}"]
[source, plain]
----
java -Xbootclasspath/p:<path_to_alpn_boot_jar> ...
----

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`.

____
[IMPORTANT]
====
Be certain to get the
link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE].
____

====
[[alpn-openjdk8-agent]]
==== ALPN agent and OpenJDK 8

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

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

[source, plain, subs="{sub-order}"]
[source, plain]
----
java -javaagent:<path_to_alpn_agent_jar> ...
----

____
[NOTE]
====
The Jetty ALPN agent works with any Java 8 version. It is _required_ if you use
an OpenJDK version up to `1.8.0_242` included, and it is _optional_ if you use an
OpenJDK version equal or greater than `1.8.0_252`.

The Jetty ALPN agent can be left on the command line even when using an OpenJDK version
equal or greater than `1.8.0_252` but we recommend to remove it from the command line
when you use OpenJDK `1.8.0_252` or later.
____

====
[[alpn-conscrypt]]
==== ALPN and Conscrypt

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

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

____
[NOTE]
====
OSGi *requires* a `ServiceLoader` implementation for Jetty to function properly.
OSGi leverages http://aries.apache.org/modules/spi-fly.html[Apache Aries SPI Fly] for this functionality.
You can read more about OSGi and `ServiceLoader` http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html[here.]
____

====
[[alpn-troubleshooting]]
==== ALPN Troubleshooting

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

[source, plain, subs="{sub-order}"]
[source, plain]
----
IllegalStateException: no ALPN processor
----
Expand Down Expand Up @@ -217,7 +214,7 @@ Refer to `ALPN` Javadocs and to the examples below for further details about cli
[[alpn-openjdk8-client-example]]
==== Client Example

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

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

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

[source, xml, subs="{sub-order}"]
[source, xml]
----
<project>

Expand Down Expand Up @@ -328,9 +325,9 @@ The solution that we use with Maven is to specify an additional command line arg

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

....
----
ALPN.debug = true;
....
----

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`.

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

Clone the OpenJDK repository with the following command:

[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ hg clone https://hg.openjdk.java.net/jdk8u/jdk8u jdk8u
$ cd !$
$ ./get_source.sh
....
----

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

[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ ./make/scripts/hgforest.sh update <tag-name>

....
----

The list of OpenJDK tags can be obtained from this page:
https://hg.openjdk.java.net/jdk8u/jdk8u/tags[OpenJDK 8 Tags].
Expand Down
2 changes: 1 addition & 1 deletion ...ation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc
View file
Open in desktop
Expand Up @@ -39,7 +39,7 @@ Below is an example application that sets up the standard `test-spec.war` webapp
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`.]
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).

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