lowRISC / lowRISC/opentitan

[site,doc] Ease documentation reading on large screen

Open
#20,803 0 comments 0 reactions 1 assignee View on GitHub

@hcallahan-lowrisc is already working on this.

Since Jan 10, 2024.

Component:Doc
Dominant language
SystemVerilog
Stars
3.6k
Forks
1.1k
Avg merge
2d 22h
Merged PRs (30d)
141

Description

### Description

Several pages cannot be easily read because the CSS definition limits the width of the content to an arbitrary width of 750 pixels. For example, `hw/ip/otp_ctrl/doc/theory_of_operation.html#partition-listing-and-description` is hardly readable because the table is always larger than the actual view.

I do not think it should be limited to a pixel size, as the results really depends on the reader's browser. Moreover whatever the viewport size, the content width is limited to 750px. I think it would be better (and far more readable) to let the reader pick the width he wants rather than locking him down.

Removing `--content-max-width: 750px;` from `site/book-theme/css/variables.css` improves a lot the read experience, but comes with its own drawback:
* right-side ToC may become a bit narrow; perhaps it could be defined with a min width based on element (`em`) rather than on pixels
* SVG diagrams may use the whole content width and become a bit oversize, it may be possible to clamp their width to a ratio of the actual elements (`em`) so that their appearance is kept in sync with the actual character size.

Thanks.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.