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

[SPARK-46923][DOCS] Limit width of configuration tables #44955

Closed
wants to merge 10 commits into from

Conversation

nchammas
Copy link
Contributor

@nchammas nchammas commented Jan 30, 2024

What changes were proposed in this pull request?

  • Assign all config tables in the documentation to the new CSS class spark-config.
    • Migrate the config table in docs/sql-ref-ansi-compliance.md from Markdown to HTML and assign it to this new CSS class as well.
  • Limit the width of the config tables to the width of the main content, and force words to break and wrap if necessary.
  • Remove a styling workaround for the documentation for spark.worker.resourcesFile that is not needed anymore thanks to these changes.
  • Remove some .global CSS rules that, due to their specificity interfere with our ability to assign simple rules that apply directly to elements.

Why are the changes needed?

Many configs and config defaults have very long names that normally cannot wrap. This causes tables to overflow the viewport. An egregious example of this is spark.scheduler.listenerbus.eventqueue.executorManagement.capacity, which has a default of spark.scheduler.listenerbus.eventqueue.capacity.

This change will force these long strings to break and wrap, which will keep the table widths limited to the width of the overall content. Because we are hard-coding the column widths, some tables will look slightly worse with this new layout due to extra whitespace. I couldn't figure out a practical way to prevent that while also solving the main problem of table overflow.

In #44755 or #44756 (whichever approach gets accepted), these config tables will be generated automatically. This will give us the opportunity to improve the styling further by setting the column width dynamically based on the content. (This should be possible in CSS, but table styling in CSS is limited and we cannot use properties like max-width.) We will also be able to insert word break opportunities so that config names wrap in a more visually pleasing manner.

Does this PR introduce any user-facing change?

Yes, it changes the presentation of tables, especially config tables, in the main documentation.

How was this patch tested?

I built the docs and compared them visually across master (left) and this branch (right).

sql-ref-ansi-compliance.html:

configuration.html#scheduling:

configuration.html#barrier-execution-mode:

spark-standalone.html:

structured-streaming-kafka-integration.html#configuration:

Was this patch authored or co-authored using generative AI tooling?

No.

@nchammas nchammas marked this pull request as ready for review January 30, 2024 20:38
@HyukjinKwon
Copy link
Member

Merged to master.

@nchammas nchammas deleted the table-styling branch January 31, 2024 05:46
@nchammas
Copy link
Contributor Author

nchammas commented Feb 1, 2024

We will also be able to insert word break opportunities so that config names wrap in a more visually pleasing manner.

For a demonstration of how we can use this technique to improve the presentation of config tables once we are programmatically generating them, refer to #44971.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants