Improvements to the Jetty documentation.

Restructured the programming guide.
Added collapsible TOC.

Signed-off-by: Simone Bordet <[email protected]>

Author: sbordet

documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch-jmx.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-arch-jmx]]
-== Jetty JMX Support
+=== Jetty JMX Support
 
 The Java Management Extensions (JMX) APIs are standard API for managing and monitoring resources such as applications, devices, services, and the Java Virtual Machine itself.
 
@@ -38,7 +38,7 @@ The Maven coordinates for the Jetty JMX support are:
 </dependency>
 ----
 
-=== Enabling JMX Support
+==== Enabling JMX Support
 
 Enabling JMX support is always recommended because it provides valuable information about the system, both for monitoring purposes and for troubleshooting purposes in case of problems.
 
@@ -67,7 +67,7 @@ In these cases, you have to enable xref:pg-arch-jmx-remote[JMX Remote Access].
 // TODO: add a section about how to expose logging once #4830 is fixed.
 
 [[pg-arch-jmx-remote]]
-=== Enabling JMX Remote Access
+==== Enabling JMX Remote Access
 
 There are two ways of enabling remote connectivity so that JMC can connect to the remote JVM to visualize MBeans.
 
@@ -148,7 +148,7 @@ include::{doc_code}/org/eclipse/jetty/docs/programming/JMXDocs.java[tags=remote]
 ----
 
 [[pg-arch-jmx-remote-authorization]]
-==== JMX Remote Access Authorization
+===== JMX Remote Access Authorization
 
 The standard `JMXConnectorServer` provides several options to authorize access, for example via JAAS or via configuration files.
 For a complete guide to controlling authentication and authorization in JMX, see https://docs.oracle.com/en/java/javase/11/management/[the official JMX documentation].
@@ -242,7 +242,7 @@ When you configure `ConnectorServer` in this way, you must set the system proper
 This is required because when the RMI server is exported, its address and port are stored in the RMI stub. You want the address in the RMI stub to be `localhost` so that when the RMI stub is downloaded to the remote client, the RMI communication will go through the SSH tunnel.
 
 [[pg-arch-jmx-annotation]]
-=== Jetty JMX Annotations
+==== Jetty JMX Annotations
 
 The Jetty JMX support, and in particular `MBeanContainer`, is notified every time a bean is added to the component tree.
 
@@ -278,24 +278,24 @@ For each type -- class or interface, the corresponding `+*.jmx.*MBean+` is looke
 For each type, the scan looks for the class-level annotation `@ManagedObject`.
 If it is found, the scan looks for method-level `@ManagedAttribute` and `@ManagedOperation` annotations; otherwise it skips the current type and moves to the next type to scan.
 
-==== @ManagedObject
+===== @ManagedObject
 
 The `@ManagedObject` annotation is used on a class at the top level to indicate that it should be exposed as an MBean.
 It has only one attribute to it which is used as the description of the MBean.
 
-==== @ManagedAttribute
+===== @ManagedAttribute
 
 The `@ManagedAttribute` annotation is used to indicate that a given method is exposed as a JMX attribute.
 This annotation is placed always on the getter method of a given attribute.
 Unless the `readonly` attribute is set to `true` in the annotation, a corresponding setter is looked up following normal naming conventions.
 For example if this annotation is on a method called `String getFoo()` then a method called `void setFoo(String)` would be looked up, and if found wired as the setter for the JMX attribute.
 
-==== @ManagedOperation
+===== @ManagedOperation
 
 The `@ManagedOperation` annotation is used to indicate that a given method is exposed as a JMX operation.
 A JMX operation has an _impact_ that can be `INFO` if the operation returns a value without modifying the object, `ACTION` if the operation does not return a value but modifies the object, and "ACTION_INFO" if the operation both returns a value and modifies the object.
 If the _impact_ is not specified, it has the default value of `UNKNOWN`.
 
-==== @Name
+===== @Name
 
 The `@Name` annotation is used to assign a name and description to parameters in method signatures so that when rendered by JMX consoles it is clearer what the parameter meaning is.

documentation/jetty-documentation/src/main/asciidoc/programming-guide/arch.adoc

@@ -16,6 +16,6 @@
 == Jetty Architecture
 
 include::arch-bean.adoc[]
-include::arch-jmx.adoc[]
-include::arch-listener.adoc[]
 include::arch-io.adoc[]
+include::arch-listener.adoc[]
+include::arch-jmx.adoc[]

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client.adoc

@@ -29,6 +29,7 @@ These are the available client libraries:
 
 If you are interested in the low-level details of how the Eclipse Jetty client libraries work, or are interested in writing a custom protocol, look at the xref:pg-client-io-arch[Client I/O Architecture].
 
+include::client-io-arch.adoc[]
 include::http/client-http.adoc[]
 include::http2/client-http2.adoc[]
-include::client-io-arch.adoc[]
+include::websocket/client-websocket.adoc[]

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc

@@ -12,12 +12,12 @@
 //
 
 [[pg-client-http-api]]
-=== HttpClient API Usage
+==== HttpClient API Usage
 
 `HttpClient` provides two types of APIs: a blocking API and a non-blocking API.
 
 [[pg-client-http-blocking]]
-==== HttpClient Blocking APIs
+===== HttpClient Blocking APIs
 
 The simpler way to perform a HTTP request is the following:
 
@@ -77,7 +77,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 In the example above, when the 5 seconds expire, the request/response cycle is aborted and a `java.util.concurrent.TimeoutException` is thrown.
 
 [[pg-client-http-non-blocking]]
-==== HttpClient Non-Blocking APIs
+===== HttpClient Non-Blocking APIs
 
 So far we have shown how to use Jetty HTTP client in a blocking style -- that is, the thread that issues the request blocks until the request/response conversation is complete.
 
@@ -135,9 +135,6 @@ This makes Jetty HTTP client suitable for HTTP load testing because, for example
 
 Have a look at the link:{JDURL}/org/eclipse/jetty/client/api/Request.Listener.html[`Request.Listener`] class to know about request events, and to the link:{JDURL}/org/eclipse/jetty/client/api/Response.Listener.html[`Response.Listener`] class to know about response events.
 
-[[pg-client-http-content]]
-==== HttpClient Content Handling
-
 [[pg-client-http-content-request]]
 ===== Request Content Handling
 

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-authentication.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-client-http-authentication]]
-=== HttpClient Authentication Support
+==== HttpClient Authentication Support
 
 Jetty's `HttpClient` supports the `BASIC` and `DIGEST` authentication mechanisms defined by link:https://tools.ietf.org/html/rfc7235[RFC 7235], as well as the SPNEGO authentication mechanism defined in link:https://tools.ietf.org/html/rfc4559[RFC 4559].
 
@@ -76,5 +76,5 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 See also the xref:pg-client-http-proxy-authentication[proxy authentication section] for further information about how authentication works with HTTP proxies.
 
 [[pg-client-http-authentication-spnego]]
-=== HttpClient SPNEGO Authentication Support
+===== HttpClient SPNEGO Authentication Support
 TODO

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-client-http-configuration]]
-=== HttpClient Configuration
+==== HttpClient Configuration
 
 `HttpClient` has a quite large number of configuration parameters.
 Please refer to the `HttpClient` link:{JDURL}/org/eclipse/jetty/client/HttpClient.html[javadocs] for the complete list of configurable parameters.
@@ -26,7 +26,7 @@ The most common parameters are:
 * `HttpClient.maxRequestsQueuedPerDestination`: the max number of requests queued (defaults to 1024).
 
 [[pg-client-http-configuration-tls]]
-==== HttpClient TLS Configuration
+===== HttpClient TLS Configuration
 
 `HttpClient` supports HTTPS requests out-of-the-box like a browser does.
 
@@ -64,9 +64,9 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 Please refer to the `SslContextFactory.Client` link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Client.html[javadocs] for the complete list of configurable parameters.
 
 [[pg-client-http-configuration-tls-truststore]]
-==== HttpClient TLS TrustStore Configuration
+====== HttpClient TLS TrustStore Configuration
 TODO
 
 [[pg-client-http-configuration-tls-client-certs]]
-==== HttpClient TLS Client Certificates Configuration
+====== HttpClient TLS Client Certificates Configuration
 TODO

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-cookie.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-client-http-cookie]]
-=== HttpClient Cookie Support
+==== HttpClient Cookie Support
 
 Jetty's `HttpClient` supports cookies out of the box.
 
@@ -65,7 +65,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 The example above will retain only cookies that come from the `google.com` domain or sub-domains.
 
 // TODO: move this section to server-side
-==== Special Characters in Cookies
+===== Special Characters in Cookies
 
 Jetty is compliant with link:https://tools.ietf.org/html/rfc6265[RFC6265], and as such care must be taken when setting a cookie value that includes special characters such as `;`.
 

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-intro.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-client-http-intro]]
-=== HttpClient Introduction
+==== HttpClient Introduction
 
 The Jetty HTTP client module provides easy-to-use APIs and utility classes to perform HTTP (or HTTPS) requests.
 

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-proxy.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-client-http-proxy]]
-=== HttpClient Proxy Support
+==== HttpClient Proxy Support
 
 Jetty's `HttpClient` can be configured to use proxies to connect to destinations.
 
@@ -33,7 +33,7 @@ Configured in this way, `HttpClient` makes requests to the HTTP proxy (for plain
 Proxying is supported for both HTTP/1.1 and HTTP/2.
 
 [[pg-client-http-proxy-authentication]]
-==== Proxy Authentication Support
+===== Proxy Authentication Support
 
 Jetty's `HttpClient` supports proxy authentication in the same way it supports xref:pg-client-http-authentication[server authentication].
 

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-transport.adoc

@@ -12,7 +12,7 @@
 //
 
 [[pg-client-http-transport]]
-=== HttpClient Pluggable Transports
+==== HttpClient Pluggable Transports
 
 Jetty's `HttpClient` can be configured to use different transports to carry the semantic of HTTP requests and responses.
 
@@ -57,7 +57,7 @@ Applications are typically not aware of the actual protocol being used.
 This allows them to write their logic against a high-level API that hides the details of the specific protocol being used over the network.
 
 [[pg-client-http-transport-http11]]
-==== HTTP/1.1 Transport
+===== HTTP/1.1 Transport
 
 HTTP/1.1 is the default transport.
 
@@ -74,7 +74,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 ----
 
 [[pg-client-http-transport-http2]]
-==== HTTP/2 Transport
+===== HTTP/2 Transport
 
 The HTTP/2 transport can be configured in this way:
 
@@ -88,7 +88,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPCli
 `HttpClientTransportOverHTTP2` uses `HTTP2Client` to format high-level semantic HTTP requests (like "GET resource /index.html") into the HTTP/2 specific format.
 
 [[pg-client-http-transport-fcgi]]
-==== FastCGI Transport
+===== FastCGI Transport
 
 The FastCGI transport can be configured in this way:
 
@@ -102,7 +102,7 @@ In order to make requests using the FastCGI transport, you need to have a FastCG
 The FastCGI transport is primarily used by Jetty's xref:fastcgi[FastCGI support] to serve PHP pages (WordPress for example).
 
 [[pg-client-http-transport-dynamic]]
-==== Dynamic Transport
+===== Dynamic Transport
 
 The static transports work well if you know in advance the protocol you want to speak with the server, or if the server only supports one protocol (such as FastCGI).
 

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http2/client-http2.adoc

@@ -57,7 +57,7 @@ A _session_ typically has a long life -- once the TCP connection is established,
 include::../../http2.adoc[tag=multiplex]
 
 [[pg-client-http2-flow-control]]
-===== HTTP/2 Flow Control
+==== HTTP/2 Flow Control
 
 include::../../http2.adoc[tag=flowControl]
 
@@ -84,7 +84,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http2/HTTP2C
 IMPORTANT: Applications must know in advance whether they want to connect to a clear-text or encrypted port, and pass the `SslContextFactory` parameter accordingly to the `connect(...)` method.
 
 [[pg-client-http2-configure]]
-===== Configuring the Session
+==== Configuring the Session
 
 The `connect(...)` method takes a `Session.Listener` parameter.
 This listener's `onPreface(...)` method is invoked just before establishing the connection to the server to gather the client configuration to send to the server.

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/websocket/client-websocket.adoc

@@ -12,6 +12,6 @@
 //
 
 [[pg-client-websocket]]
-=== WebSocket Client Libraries
+=== WebSocket Client
 
 TODO

documentation/jetty-documentation/src/main/asciidoc/programming-guide/index-docinfo.html

@@ -0,0 +1,3 @@
+<link rel="stylesheet" href="../styles.css">
+<link rel="stylesheet" href="../toc.css">
+<script src="../toc.js"></script>

documentation/jetty-documentation/src/main/asciidoc/programming-guide/index.adoc

@@ -12,9 +12,10 @@
 //
 
 :doctitle: Eclipse Jetty: Programming Guide
-:toc-title: Programming Guide
+:toc-title: Jetty Programming Guide
 :breadcrumb: Home:../index.html | Programming Guide:./index.html
 :idprefix: pg-
+:docinfo: private-head
 
 include::../config.adoc[]
 include::.asciidoctorconfig[]

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-application.adoc

@@ -12,19 +12,19 @@
 //
 
 [[pg-server-http-application]]
-=== Writing HTTP Server Applications
+===== Writing HTTP Server Applications
 
 Writing HTTP applications is typically simple, especially when using blocking APIs.
 However, there are subtle cases where it is worth clarifying what a server application should do to obtain the desired results when run by Jetty.
 
 [[pg-server-http-application-1xx]]
-==== Sending 1xx Responses
+====== Sending 1xx Responses
 
 The link:https://tools.ietf.org/html/rfc7231#section-5.1.1[HTTP/1.1 RFC] allows for `1xx` informational responses to be sent before a real content response.
 Unfortunately the servlet specification does not provide a way for these to be sent, so Jetty has had to provide non-standard handling of these headers.
 
 [[pg-server-http-application-100]]
-===== 100 Continue
+====== 100 Continue
 
 The `100 Continue` response should be sent by the server when a client sends a request with an `Expect: 100-continue` header, as the client will not send the body of the request until the `100 Continue` response has been sent.
 
@@ -39,7 +39,7 @@ include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPSer
 ----
 
 [[jetty-102-processing]]
-===== 102 Processing
+====== 102 Processing
 
 link:https://tools.ietf.org/html/rfc2518[RFC 2518] defined the `102 Processing` status code that can be sent: