sphinx-doc / sphinx-doc/sphinx

Object definition lists get cramped in HTML

Open
#9,770 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

html theme type:bug
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
  1. Add your own object type with add_object_type() (unsure if this is needed)
  2. Add a bunch of object definitions after each other (see example above)
  3. Generate HTML output
Expected behavior

Reasonable margin between each definition.

Your project

N/A

Screenshots

Object definition list:

Screenshot 2021-10-25 at 09-44-06 Configuration Parameters Used by the ThinLinc Client — The ThinLinc Administrator's Guide

Normal definition list:

Screenshot 2021-10-25 at 09-44-56 Configuration Parameters Used by the ThinLinc Client — The ThinLinc Administrator's Guide

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

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.