search

cherab / core

The core source repository for the Cherab project.
https://www.cherab.info
Other
45 stars 24 forks source link

List bullets are not rendered in documentation due to CSS RTD theme overrides #467

Open vsnever opened 2 months ago

vsnever commented 2 months ago

When building documentation with: docutils==0.20.1, Sphinx==7.4.7 and sphinx-rtd-theme==2.0.0, the list bullets are not rendered:

  1. Screenshot 2024-09-05 at 16 30 44
  2. Screenshot 2024-09-05 at 16 32 19

The reason is that the default CSS styles are overridden in in the docs/source/cons.py: https://github.com/cherab/core/blob/26595cb6101e14d6a3eeb1b7421024425114c7a1/docs/source/conf.py#L144-L148

Removing list-style:none for ul, ol, dl and li tags:

ul,ol,dl{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}

in docs/source/static/theme_overrides.css returns the bullet rendering to normal, but the zero margins defined in several places in that file result in weird formatting of the HTML documentation.

I was trying to tweak other parameters in docs/source/static/theme_overrides.css, but in my opinion the best output is obtained using the default RTD theme CSS styles. Shouldn't we just comment out the html_context override in docs/source/cons.py?

jacklovell commented 1 month ago

theme_overrides.css has been there since at least 2017: I don't know whether it's still necessary or whether the problem it was working around has been solved upstream in sphinx-rtd-theme since. @CnlPepper can you remember exactly why this was added in the first place?