On Fri, 12 Jan 2024 18:52:46 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... > > Hannes Wallnöfer has updated the pull request incrementally with one > additional commit since the last revision: > > Consolidate TOC functionality into new TableOfContents class The last commit ([70d06e5](https://github.com/openjdk/jdk/pull/17062/commits/70d06e59711f61f732bc64529e26df5282671bfd)) moves the TOC-related methods from `HtmlDocletWriter` to a new `TableOfContents` class. This includes some not totally obvious changes: - `<h2>` headings in the main description are now added directly to the TOC/`ListBuilder` instead of collecting them separately and then adding them as a complete sublist. This has a few other consequences: - Method `ListBuilder.addNested(HtmlTree)` is no longer needed and has been removed, all sublists are added via a sequence of `push`-`add`-`pop`. - The stack in `ListBuilder` now stacks both the current list and the current list item as an `HtmlTree[]` array of length 2. This is because a nested list is only added to the parent list item after it is popped to make sure it is not empty. - The constant values page did previously not add `tabindex="0"` attributes. This has been fixed which required the respective test to be updated. ------------- PR Comment: https://git.openjdk.org/jdk/pull/17062#issuecomment-1889842593
