Style semantic markup roles#924
Conversation
Add visual styling for Sphinx semantic roles that are currently indistinguishable from plain bold, italic, or inline code: - CLI/Commands (green tint): :command:, :program:, :makevar: - Paths/Patterns (amber tint): :file:, :samp:, :regexp: - Environment/Options (purple tint): :envvar:, :option: - Metadata (grey tint): :manpage:, :mimetype:, :mailheader:, :newsgroup: Includes light and dark mode support and kitchen-sink examples.
| For example, ``menuselection`` should break when it is too long to fit on a | ||
| single line. | ||
|
|
||
| Semantic roles |
There was a problem hiding this comment.
The preview looks nice, AFAICT: https://furo--924.org.readthedocs.build/kitchen-sink/generic.html#semantic-roles
| uses replaceable parts. Regular expressions: :regexp:`^foo.*bar$`. | ||
|
|
||
| **Environment variables and options:** | ||
| Set :envvar:`PATH` or :envvar:`HOME` in your shell. Pass :option:`--verbose` or |
There was a problem hiding this comment.
I wonder if the env vars should have a $ prepended as a visual cue. Let's wait what Pradyun has to say once he comes back home..
| :makevar:`CFLAGS` are also styled distinctly. | ||
|
|
||
| **File paths, samples, and patterns:** | ||
| Edit :file:`/etc/hosts` or :file:`conf.py`. A sample like :samp:`print({name})` |
There was a problem hiding this comment.
We probably need an example with python3.{x} in a path, not just in a sample.
There was a problem hiding this comment.
Tip
@him2him2 I noticed that you posted a bit of RST in a GH comment which renders Markdown. It's a bit unobvious but is actually possible to embed RST in MD by wrapping it with double backticks and a whitespace between the outer double backticks and the inner RST content with backticks that should remain rendered as is:
:file:`/usr/bin/python3.{x}`
| italic, or inline code. Each group below has a distinct visual style. | ||
|
|
||
| **CLI commands and build variables:** | ||
| Use :command:`curl` or :program:`python3` to run commands. Build variables like |
There was a problem hiding this comment.
Let's add a CLI arg to the curl example to show that a command can contain multiple whitespace-delimited components while a program generally wouldn't, IIUC what the Sphinx docs imply.
|
@him2him2 I noticed that the background colors are better visible in dark mode but when the light color scheme is active, it's barely noticeable. Have you looked into the contrast difference? |
- Increase light mode alpha from 50% to 75% for better contrast - Add CLI args to curl example to show multi-word commands - Add file path example with replaceable part
|
@webknjaz Good catch — I've bumped the light mode alpha from 50% ( |
|
Nice! I like it better now :) |
2 participants
Summary
Adds visual styling for Sphinx semantic roles that are currently indistinguishable from plain bold, italic, or inline code. Addresses #890.
Roles are grouped into four visual categories, each with a subtle tinted background that works in both light and dark mode:
:command:,:program:,:makevar::file:,:samp:,:regexp::envvar:,:option::manpage:,:mimetype:,:mailheader:,:newsgroup:Files changed
src/furo/assets/styles/variables/_colors.scss-- CSS custom properties (light + dark)src/furo/assets/styles/content/_semantic-roles.sass-- new stylesheetsrc/furo/assets/styles/content/_index.sass-- register the new moduledocs/kitchen-sink/generic.rst-- demo section with examples of all rolesNote
This is a first pass at the styling. I'm very open to feedback on the colour choices, groupings, or overall approach -- if anything should be tweaked or done differently, please let me know and I'll update accordingly.
Test plan
:guilabel:,:kbd:,:menuselection:styles are unaffected