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. - The `SEARCH` link that also served as label for the search input field has moved to the top navigation bar. The search input field uses "Search" as placeholder and also got a "Search in documentation" aria-label attribute. - The code to locate target anchors in relation to the header navigation has been much improved. For this purpose, new CSS custom properties `--top-nav-height`, `--sub-nav-height` and `--nav-height` have been introduced which are also updated dynamically to avoid any flickering seen in the previous version. - Also introduced were a few new CSS custom properties and rules for font sizes that line height that were previously missing. One example is package pages which previously had different line spacing depending on whether a `<p>` tag was present or not. - The `Navigation` has been simplified a bit and now uses a single `addOverviewLink` to generate a link to the overview page, the first module page, or the first package page, depending on configuration. a new `addPageElementLink` method creates a link to the current page element. - Several tests were added to `TestNavigation` and `TestModuleNavigation` to check the navigation links in previously untested configurations. - Some functionality in `search.js.template` such as implementation of the mobile menu and creating the heading anchor links was not search related and therefore belonged into `script.js`. This required `script.js` localized properties to be injected into `script.js` which is therefore renamed to `script.js.template` Unfortunately, git did not recognize this as renaming but rather as removal of `script.js` and addition of `script.js.template`, but the file is pretty much unchanged up to line 232 with the new code starting in line 233. - The reset `x` button in the search input field and the new TOC filter field behave a bit differently than previously in that they are only visible if there is some text in the input field. - An empty string `""` in a fragment was so far interpreted as no fragment. However, the empty fragment is now used to navigate to the top of the page (this is standard behaviour and implemented in all browsers and different from clicking on a link without `#` which results in reloading the page rather than scrolling to the top). This required the changes in `DocLink` and `HtmlLinkInfo` as well as the `LinkChecker` test. - Empty and single element lists are required or hard to avoid in breadcrumb and TOC navigation (empty list is present in subheader without breadcrumb links to keep the search input in place, and singleton lists often appear in sublists for single members or headings). Therefore, ample exceptions had to be made in the `TestSingletonLists` test. - The `TestSubTitle` test was removed as module and package subtitles have been replaced by the breadcrumb links. ------------- Commit messages: - Add navigation tests for untested configurations. - Consolidate stylesheet changes - Fix selector - Adapt tests to previous commit - Use more appropriate HTML elements, add ARIA label to toc. - JDK-8320458: Improve structural navigation in API documentation Changes: https://git.openjdk.org/jdk/pull/17062/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17062&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8320458 Stats: 2987 lines in 70 files changed: 1627 ins; 865 del; 495 mod Patch: https://git.openjdk.org/jdk/pull/17062.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/17062/head:pull/17062 PR: https://git.openjdk.org/jdk/pull/17062
