sphinx-doc / sphinx-doc/sphinx
Object definition lists get cramped in HTML
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
If I have a list of object definitions, e.g.
.. my-object:: ObjectA
This is an awesome object
.. my-object:: ObjectB
This is also an awesome object!
Then the HTML output of this gets very cramped compared to normal definition lists (at least with Alabaster).
The problem is that a normal definition list with multiple items gets outputted as a single <dl>. However multiple object definitions like the example above get one <dl> per definition. There is a whole bunch of CSS that removes the margins if you have multiple <dl> after each other, something I assume doesn't happen with normal definition lists.
For normal definition lists the surrounding elements generally have margins that makes sure things look okay, but that doesn't happen with the object definitions.
How to Reproduce
- Add your own object type with
add_object_type()(unsure if this is needed) - Add a bunch of object definitions after each other (see example above)
- Generate HTML output
Expected behavior
Reasonable margin between each definition.
Your project
N/A
Screenshots
Object definition list:

Normal definition list:

OS
Linux
Python version
3.6.12
Sphinx version
4.2.0
Sphinx extensions
No response
Extra tools
No response
Additional context
For now I've worked around this by applying this style sheet:
dl:not(.simple) > dd:last-child > :last-child {
margin-bottom: 1em;
}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue by defining a custom object type with add_object_type(), adding consecutive object definitions, and generating HTML. Inspect the generated definition-list markup and its styling alongside a normal definition list. Done means consecutive object definitions have reasonable margins without requiring the reported workaround stylesheet.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css, python
- Domain
- documentation, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100