search

Pylons / pylons-sphinx-themes

Sphinx themes for projects under the Pylons Project, but in a Python package instead of git submodule.
Other
2 stars 2 forks source link

Styles for default_role are misleading, should use monospace font #7

Open stevepiercy opened 7 years ago

stevepiercy commented 7 years ago

Reference: https://github.com/Pylons/webob/pull/335#discussion_r134369820

Parameters for Python classes, methods, and functions have crappy formatting. They use the <cite> HTML tag, which most browsers display as italicized text by default. Unfortunately parameters do not have a useful link target. As a result, <cite> is doubtful to be semantically correct as it cannot be easily determined what is being cited.

Ideally the parameters would be styled to appear as code or in a monospaced font face without italicization to relieve visual dissonance.

The simple fix would be to add cite to this selector:

cite, tt, code {
    background-color: transparent;
    color: #222;
    font-family: Consolas, "andale mono", "lucida console", monospace;
}

The following are examples for reference only.

reST source:

`language_tags`

Yields:

<cite>language_tags</cite>

When there are useful linkable targets, it looks fine. Using Pyramid's docs as an example...

reST source:

:ref:`firstapp_chapter`

renders as:

<a class="reference internal" href="narr/firstapp.html#firstapp-chapter"><span class="std std-ref">Creating Your First Pyramid Application</span></a>

reST source using autodoc:

:mod:`pyramid.authentication`

renders as:

<a class="reference internal" href="api/authentication.html"><code class="docutils literal"><span class="pre">pyramid.authentication</span></code></a>