Invisible mobile top navigation bar

[cjmayo]

Problem

With style_nav_header_background set to white (as the example in https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#theme-options) when the browser is resized to mobile proportions the top navigation bar is invisible (all white).

2026bb6 from #1132 set background to theme_style_nav_header_background if it is set. But the .wy-nav-top a color is hard-coded to #fff (white) in theme.css.

Looks like this part:

.wy-nav-top a{color:#fff;font-weight:700}

And .wy-nav-top color for the hamburger too.

Reproducible Project

Create a project with sphinx-quickstart

Edit conf.py:

html_theme = 'sphinx_rtd_theme'

html_theme_options = {
 'style_nav_header_background': 'white',
}

make html

Open generated index.html and reduce page width until layout changes to mobile style.

Environment Info

• Python Version: 3.10.2
• Sphinx Version: 4.4.0
• RTD Theme Version: 1.0.0

[nienn]

Hi @cjmayo, thanks for reporting this.

I believe that, at first, this was not the intended use for this option. It is the one suggested by the docs thought, so we need to consider either changing the docs or the implementation.

A quick fix you can implement is to add a custom CSS file to your docs. This will allow you to target the bar child elements and adjust their contrast.

Additional notes

Current documentation

• Theme options
• Table of contents options

From the first link it's suggested that 'style_nav_header_background' can be set to 'white' and it will just work. We then expect the code to take care of any necessary adjustments. This is not what happens however.

Current code implementation

The only thing this option actually does is changing the background color to the .wy-side-nav-search and .wy-nav-top elements, without doing any check on color contrast for inner elements.

.wy-side-nav-search:

sphinx_rtd_theme/sphinx_rtd_theme/layout.html

Line 133 in d64dadf

<div class="wy-side-nav-search" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>

.wy-nav-top:

sphinx_rtd_theme/sphinx_rtd_theme/layout.html

Line 195 in d64dadf

<nav class="wy-nav-top" aria-label="{{ _('Mobile navigation menu') }}" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>

Proposed solutions

Option A) The code should make a check on color contrast, and alter the color accordingly for child elements of both the affected elements.

Option B) The docs should be altered to highlight the use of darker colors (by default) and to inform on further possible actions for advanced customization.

change: 'style_nav_header_background': 'white'

to: 'style_nav_header_background': '#222'

in: https://github.com/readthedocs/sphinx_rtd_theme/blame/master/docs/configuring.rst#L23

change:

.. confval:: style_nav_header_background

    Changes the background of the search area in the navigation bar. The value
    can be anything valid in a CSS `background` property.

    :type: string
    :default: ``#2980B9``

to: Add information about targeting additional selectors that might require custom adjustments with a custom CSS file.

in: https://github.com/readthedocs/sphinx_rtd_theme/blame/master/docs/configuring.rst#L169-L175