Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8344301: Refine stylesheet for API docs #23678

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Conversation

hns
Copy link
Member

@hns hns commented Feb 18, 2025

This is an extensive update to the JavaDoc stylesheet that focuses on layout and typography, with the purpose of making API docs easier to read and use.

List of changes:

  • Slightly increase text and navigation fonts to improve readability and to better match the code font (which remains unchanged).
  • Fix font size and line height inconsistencies in many places.
  • Limit the maximal width of page content to improve readability on large displays. If more horizontal space is available, page content is centered.
  • Remove light gray section background in class and module pages to simplify and unclutter the layout.
  • Add a subtle gray background to code elements in normal text to set them apart.
  • Highlight headings of member details when they are used as link targets.
  • Reserve use of bold font in member summary tables to element names to make them easier to spot and reduce visual noise.
  • Slightly reduce width of TOC sidebar and use ellipsis (...) if content does not fit (but long signatures continue to wrap).
  • Make method signatures in details easier to read on small dispays by allowing them to wrap before parameters and throws sections.
  • Make tabs on top of summary tables scroll instead of wrapping if they overflow the available horizontal space.
  • Hide TOC sidebar and copy-to-clipboard buttons in addition to the top navigation bar when printing a page.
  • Improve styling of additional HTML files in doc-files directories.
  • Reduce rollover animations and remove smooth scrolling in order to improve accessibility.
  • Add background to <pre> elements (will look great with JDK-8346118).
  • Various cleanup.

There are too many non-trivial changes in the stylesheet to try explaining them here, but of course I'll be happy to discuss every change on request.

Full JDK API docs are available for testing and comparison.


Progress

  • Change must be properly reviewed (1 review required, with at least 1 Reviewer)
  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue

Issue

  • JDK-8344301: Refine stylesheet for API docs (Enhancement - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/23678/head:pull/23678
$ git checkout pull/23678

Update a local copy of the PR:
$ git checkout pull/23678
$ git pull https://git.openjdk.org/jdk.git pull/23678/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 23678

View PR using the GUI difftool:
$ git pr show -t 23678

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/23678.diff

Using Webrev

Link to Webrev Comment

hns added 2 commits February 18, 2025 13:52
 - limit page content width and center-align on larger displays
 - unclutter pages by removing light gray section backgrounds
 - slightly increase text and nav font sizes to match code font
 - highlight code in text with subtle gray background
 - adjust fonts and spacing in lots of elements
 - implement target highlight for class member details
 - use bold font for member names only in member summary tables
 - improve layout of method signatures on small displays
 - make table tabs not wrap on small displays
 - hide table of contents in printed page
 - remove animations and smooth scrolling in favor of accessibility
 - get rid of negative margin hacks
@bridgekeeper
Copy link

bridgekeeper bot commented Feb 18, 2025

👋 Welcome back hannesw! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk
Copy link

openjdk bot commented Feb 18, 2025

❗ This change is not yet ready to be integrated.
See the Progress checklist in the description for automated requirements.

@openjdk openjdk bot added the rfr Pull request is ready for review label Feb 18, 2025
@openjdk
Copy link

openjdk bot commented Feb 18, 2025

@hns The following label will be automatically applied to this pull request:

  • javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

@openjdk openjdk bot added the javadoc javadoc-dev@openjdk.org label Feb 18, 2025
@mlbridge
Copy link

mlbridge bot commented Feb 18, 2025

Webrevs

hns added 2 commits February 21, 2025 10:02
 - reduce rollover transitions on headings and snippets
 - add background and padding to <pre> elements
 - slightly brighten snippets background
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
javadoc javadoc-dev@openjdk.org rfr Pull request is ready for review
Development

Successfully merging this pull request may close these issues.

1 participant