Integrated: JDK-8320458: Improve structural navigation in API documentation

[Hannes Wallnöfer]

On Mon, 11 Dec 2023 16:36:09 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> This is a rather big change to update the structural navigation in API documentation generated by JavaDoc. It adds a table of contents for the current page to module, package, and class documentation, and replaces the old sub-navigation bar with a breadcrumb-style links in those pages. The table of contents is displayed as sidebar on wide/desktop displays and integrated into the collapsible menu for narrow/mobile displays. The generated docs can be browsed here:
> 
> https://cr.openjdk.org/~hannesw/8320458/api.00/
> 
> This change includes improvements in `stylesheet.css` and `script.js` that are not strictly related to the navigation changes, but happened as a consequence of the necessary restructuring. All these are described together with the more on-topic changes in the list below.
> 
>  - The table of contents is composed as the respective writers generate the pages. For this purpose, `HtmlDocletWriter` has a new `tocBuilder` field of new type `ListBuilder`. If the field is not `null` it is used to build the table of contents as the page is built using either one of the  new`HtmlDocletWriter.addToTableOfContents` methods or the `ListBuilder` directly.
>  - Once the TOC is built, `HtmlDocletWriter.getSideBar` is used to generate the markup for the sidebar and it is added to the page via the `BodyContents.setSideContent` method.
>  - Both existing navigation bars (top and sub-navigation) get an additional `<div>` container with CSS class `nav-content` that uses a flex layout for its content. This also handles vertical positioning, so the old workaround for vertical of the language version label in `Docs.gmk` is not necessary anymore.
>  - Apart from modules, packages, and classes, other pages that were converted to obtain a table of contents are the "Constant Field Values" page and the Help page. 
>  - Originally, I used the `<aside>` element for the sidebar, but I learned that this was the wrong element as it is meant for content that is not strictly related to the main content of the page. The prevailing notion seems to be that a table of contents is a navigation element and therefore should use the `<nav>` element, so I used that for the TOC sidebar. The same applies for the breadcrumbs sub-navigation, so I left the header `<nav>` element wrapped around both top and sub-navigation.
>  - For the new lists in TOC and breadcrumbs I used ordered list elements `<ol>` instead of unordered `<ul>` we use everywhere else, as that is what should be used when list order is important...

This pull request has now been integrated.

Changeset: 81df265e
Author:    Hannes Wallnöfer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/81df265e41d393cdde87729e091dd465934071fd
Stats:     3104 lines in 71 files changed: 1670 ins; 873 del; 561 mod

8320458: Improve structural navigation in API documentation

Reviewed-by: erikj, jjg

-------------

PR: https://git.openjdk.org/jdk/pull/17062