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 8 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>
16 changes: 8 additions & 8 deletions jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
View file
Open in desktop
Expand Up @@ -90,7 +90,7 @@ 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> ...
----
Expand Down Expand Up @@ -121,7 +121,7 @@ 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> ...
----
Expand Down Expand Up @@ -178,7 +178,7 @@ ____

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 +217,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 +257,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 +294,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 @@ -427,7 +427,7 @@ 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 !$
Expand All @@ -436,7 +436,7 @@ $ ./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>

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[]
----
4 changes: 2 additions & 2 deletions ...on/src/main/asciidoc/administration/annotations/using-annotations-embedded.adoc
View file
Open in desktop
Expand Up @@ -39,7 +39,7 @@ The example also adds in the configuration classes that are responsible for JNDI

The code is as follows:

[source, java, subs="{sub-order}"]
[source, java]
----
import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server;
Expand Down Expand Up @@ -101,7 +101,7 @@ On lines 30, 33 and 37 JNDI resources that we will be able to reference with @Re

With the setup above, a servlet that uses annotations and Jetty will honour the annotations when the webapp is deployed can be created:

[source, java, subs="{sub-order}"]
[source, java]
----
import javax.annotation.security.DeclareRoles;
import javax.annotation.security.RunAs;
Expand Down
4 changes: 2 additions & 2 deletions ...cumentation/src/main/asciidoc/administration/annotations/using-annotations.adoc
View file
Open in desktop
Expand Up @@ -135,7 +135,7 @@ It will match all `ServletContainerInitializer` classed not explicitly named in

Here is an example, setting the context attribute in code (although you can also do the link:#intro-jetty-configuration-webapps[same in xml]):

[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder",
Expand All @@ -154,7 +154,7 @@ In this case, you can define the `org.eclipse.jetty.containerInitializerExclusio
This is a regular expression that defines http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[patterns] of classnames that you want to exclude.
Here's an example, setting the context attribute in code, although you may do exactly the link:#intro-jetty-configuration-webapps[same in xml]:

[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",
Expand Down
2 changes: 1 addition & 1 deletion ...-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc
View file
Open in desktop
Expand Up @@ -79,7 +79,7 @@ Default value is the empty list.

A typical configuration could be:

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

Expand Down
2 changes: 1 addition & 1 deletion jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc
View file
Open in desktop
Expand Up @@ -38,7 +38,7 @@ The debug handler can be added to Jetty by activating the debug module.

==== Embedded usage

[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server(8080);
RolloverFileOutputStream outputStream = new RolloverFileOutputStream("MeinLogPfad/yyyy_mm_dd.request.log", true,10);
Expand Down
2 changes: 1 addition & 1 deletion jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc
View file
Open in desktop
Expand Up @@ -39,7 +39,7 @@ _____
The `DefaultHandler` will also handle serving out the `flav.ico` file should a request make it through all of the other handlers without being resolved.
_____

[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
Expand Down
2 changes: 1 addition & 1 deletion jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc
View file
Open in desktop
Expand Up @@ -55,7 +55,7 @@ Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
This example allow 30 requests at a time:

[source, xml, subs="{sub-order}"]
[source, xml]
----
<filter>
<filter-name>DoSFilter</filter-name>
Expand Down
2 changes: 1 addition & 1 deletion jetty-documentation/src/main/asciidoc/administration/extras/header-filter.adoc
View file
Open in desktop
Expand Up @@ -55,7 +55,7 @@ ____
Each action must be separated by a comma.
____

[source, xml, subs="{sub-order}"]
[source, xml]
----
<filter>
<filter-name>HeaderFilter</filter-name>
Expand Down