On Mon, 11 Dec 2023 16:36:09 GMT, Hannes Wallnöfer <hann...@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 <hann...@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
