Skip to content

Commit

Permalink
Issue #5603 - Single page documentation (#5636)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@WalkerWatch @joakime
WalkerWatch and joakime committed Nov 20, 2020
1 parent fcfa72e commit 41bf953
Show file tree
Hide file tree
Showing 215 changed files with 1,711 additions and 7,176 deletions.
213 changes: 4 additions & 209 deletions jetty-documentation/pom.xml
View file
@@ -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
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
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[]
----

0 comments on commit 41bf953

Please sign in to comment.