From 52499bfeea9d090802cd9b4ab86de61265fb460e Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Mon, 25 Jan 2021 15:31:37 +0100 Subject: [PATCH 1/2] Improvements to the Jetty documentation. Introduced collapsible TOC via Asciidoctor's docinfo customization. Signed-off-by: Simone Bordet --- .../src/main/asciidoc/config.adoc | 2 +- .../operations-guide/index-docinfo.html | 2 + .../main/asciidoc/operations-guide/index.adoc | 1 + jetty-documentation/src/main/asciidoc/toc.css | 26 ++++ jetty-documentation/src/main/asciidoc/toc.js | 121 ++++++++++++++++++ 5 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 jetty-documentation/src/main/asciidoc/operations-guide/index-docinfo.html create mode 100644 jetty-documentation/src/main/asciidoc/toc.css create mode 100644 jetty-documentation/src/main/asciidoc/toc.js diff --git a/jetty-documentation/src/main/asciidoc/config.adoc b/jetty-documentation/src/main/asciidoc/config.adoc index 3ec1a63b77e..5528584fd01 100644 --- a/jetty-documentation/src/main/asciidoc/config.adoc +++ b/jetty-documentation/src/main/asciidoc/config.adoc @@ -17,7 +17,7 @@ :revdate: {localdate} :toc: left -:toclevels: 4 +:toclevels: 5 :idseparator: - :sectlinks: diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/index-docinfo.html b/jetty-documentation/src/main/asciidoc/operations-guide/index-docinfo.html new file mode 100644 index 00000000000..a64c8691904 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/operations-guide/index-docinfo.html @@ -0,0 +1,2 @@ + + diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc index bc4210559b7..a937b4df7d2 100644 --- a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc +++ b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc @@ -15,6 +15,7 @@ :toc-title: Operations Guide :breadcrumb: Home:../index.html | Operations Guide:./index.html :idprefix: og- +:docinfo: private-head include::../config.adoc[] include::.asciidoctorconfig[] diff --git a/jetty-documentation/src/main/asciidoc/toc.css b/jetty-documentation/src/main/asciidoc/toc.css new file mode 100644 index 00000000000..9867509a578 --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/toc.css @@ -0,0 +1,26 @@ +/* + * ======================================================================== + * Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0 which is available at + * https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 + * which is available at https://www.apache.org/licenses/LICENSE-2.0. + * + * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + * ======================================================================== + */ + +.hidden { + display: none; +} +.toc-current { + font-weight: bold; +} +.toc-item { + padding-right: 0.4em; +} +.toc-toggle { + padding-right: 0.4em; + cursor: pointer; +} diff --git a/jetty-documentation/src/main/asciidoc/toc.js b/jetty-documentation/src/main/asciidoc/toc.js new file mode 100644 index 00000000000..bce29f37bbf --- /dev/null +++ b/jetty-documentation/src/main/asciidoc/toc.js @@ -0,0 +1,121 @@ +// +// ======================================================================== +// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others. +// +// This program and the accompanying materials are made available under the +// terms of the Eclipse Public License v. 2.0 which is available at +// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0 +// which is available at https://www.apache.org/licenses/LICENSE-2.0. +// +// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +// ======================================================================== +// + +document.addEventListener('DOMContentLoaded', () => dynamicTOC()); + +function dynamicTOC() { + // Bind a click listener to all section titles. + const content = document.getElementById('content'); + const sectionTitles = content.querySelectorAll('a.link'); + for (const sectionTitle of sectionTitles) { + sectionTitle.addEventListener('click', event => collapseThenExpand(event.target.hash)); + } + + // Bind a click listener to all TOC titles. + const toc = document.getElementById('toc'); + const tocTitles = toc.querySelectorAll('a'); + for (const tocTitle of tocTitles) { + tocTitle.addEventListener('click', event => collapseThenExpand(event.target.hash)); + } + + // Add the icons to TOC nodes. + const nodes = toc.querySelectorAll('li'); + for (const node of nodes) { + const span = document.createElement('span'); + const css = span.classList; + if (node.querySelector(':scope > ul')) { + css.add('toc-toggle'); + // Font-Awesome classes. + css.add('fa'); + css.add('fa-caret-right'); + span.addEventListener('click', event => toggle(event.target)); + } else { + css.add('toc-item'); + // The "icon" is the • HTML entity. + span.appendChild(document.createTextNode('•')); + } + node.prepend(span); + } + + collapseThenExpand(document.location.hash); +} + +function collapseThenExpand(hash) { + const toc = document.getElementById('toc'); + if (hash) { + const current = toc.querySelector('a.toc-current'); + if (current) { + current.classList.remove('toc-current'); + } + const anchor = toc.querySelector('a[href="' + hash + '"'); + if (anchor) { + anchor.classList.add('toc-current'); + collapse(toc); + expand(anchor.parentNode); + } + } else { + collapse(toc); + } +} + +function collapse(node) { + const sections = node.querySelectorAll('ul'); + for (const section of sections) { + const css = section.classList; + // Always show first levels TOC titles. + const alwaysShow = css.contains('sectlevel1') || css.contains('sectlevel2'); + if (!alwaysShow) { + css.add('hidden'); + } + } + // Show the collapsed icon. + const spans = node.querySelectorAll('span.toc-toggle'); + for (const span of spans) { + const css = span.classList; + css.remove('fa-caret-down'); + css.add('fa-caret-right'); + } +} + +function expand(node) { + const root = document.getElementById('toc').querySelector('ul'); + // Show the current node and its ancestors. + let parent = node; + while (parent !== root) { + // Show the node. + parent.classList.remove('hidden'); + // Show the expanded icon. + const span = parent.querySelector(':scope > span.toc-toggle'); + if (span) { + const css = span.classList; + css.remove('fa-caret-right'); + css.add('fa-caret-down'); + } + parent = parent.parentNode; + } + // Show the children. + const children = node.querySelector(':scope > ul'); + if (children) { + children.classList.remove('hidden'); + } +} + +function toggle(span) { + const css = span.classList; + const expanded = css.contains('fa-caret-down'); + if (expanded) { + collapse(span.parentNode); + } else { + expand(span.parentNode); + } +} From 1f6c25cfb1acce101c78d302d090854887274ab4 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Mon, 25 Jan 2021 21:51:54 +0100 Subject: [PATCH 2/2] Improvements to the Jetty documentation. Fixed HTTP/2 example and documentation of the programming guide. Signed-off-by: Simone Bordet --- .../server/http/server-http-connector.adoc | 6 +++++- .../jetty/docs/programming/server/http/HTTPServerDocs.java | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc b/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc index 12b39e84f9f..c6c62600147 100644 --- a/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc +++ b/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-connector.adoc @@ -136,7 +136,11 @@ Jetty supports ALPN and encrypted HTTP/2 with this configuration: include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=tlsALPNHTTP] ---- -Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: TLS, ALPN, HTTP/1.1, HTTP/2. +Note how the ``ConnectionFactory``s passed to `ServerConnector` are in order: TLS, ALPN, HTTP/2, HTTP/1.1. Jetty starts parsing TLS bytes so that it can obtain the ALPN extension. With the ALPN extension information, Jetty can negotiate a protocol and pick, among the ``ConnectionFactory``s supported by the `ServerConnector`, the `ConnectionFactory` correspondent to the negotiated protocol. + +The fact that the HTTP/2 protocol comes before the HTTP/1.1 protocol indicates that HTTP/2 is the preferred protocol for the server. + +Note also that the default protocol set in the ALPN ``ConnectionFactory``, which is used in case ALPN is not supported by the client, is HTTP/1.1 -- if the client does not support ALPN is probably an old client so HTTP/1.1 is the safest choice. diff --git a/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java b/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java index f989267ef62..103d24402cf 100644 --- a/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java +++ b/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java @@ -331,7 +331,7 @@ public class HTTPServerDocs SslConnectionFactory tls = new SslConnectionFactory(sslContextFactory, alpn.getProtocol()); // The ServerConnector instance. - ServerConnector connector = new ServerConnector(server, tls, alpn, http11, h2); + ServerConnector connector = new ServerConnector(server, tls, alpn, h2, http11); connector.setPort(8443); server.addConnector(connector);