Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hard-to-read capitalisation of type hints in class attributes #194

Closed
jakelishman opened this issue Mar 2, 2023 · 1 comment · Fixed by #320
Closed

Hard-to-read capitalisation of type hints in class attributes #194

jakelishman opened this issue Mar 2, 2023 · 1 comment · Fixed by #320
Labels
bug Something isn't working needs triage Needs further discussion and prioritisation
Milestone

Comments

@jakelishman
Copy link
Member

jakelishman commented Mar 2, 2023

There's a CSS rule causing type hints that appear in the documentation of class attributes (such as those created by @dataclasses.dataclass) to be all upper-cased. I'm not certain which exact objects this is intending to capitalise, but type-hints should probably be exempt, since they're Python objects that are case-sensitive if people want to look them up / import them.

For example, on this page for an algorithms dataclass, the attributes are given all in uppercase. The Sphinx-generated HTML for a single attribute is (linebreaks inserted):

<dt class="sig sig-object py" id="qiskit.algorithms.optimizers.OptimizerState.x">
<span class="sig-name descname"><span class="pre">x</span></span>
<em class="property">
  <span class="p"><span class="pre">:</span></span>
  <span class="w"> </span>
  <span class="pre">Union</span>
  <span class="p"><span class="pre">[</span></span>
  <span class="pre">float</span>
  <span class="p"><span class="pre">,</span></span>
  <span class="w"> </span>
  <span class="pre">numpy.ndarray</span>
  <span class="p"><span class="pre">]</span></span>
</em>
<a class="headerlink" href="#qiskit.algorithms.optimizers.OptimizerState.x" title="Permalink to this definition"></a>
</dt>
<dd><p>Current optimization parameters.</p></dd>

(so Union, Optional etc are correctly cased in the HTML). The causing CSS rule seems to be:

article.pytorch-article .class em.property {
	text-transform: uppercase;
	font-style: normal;
	color: var(--purple);
	font-size: 1rem;
	letter-spacing: 0;
	padding-right: 0.75rem;
}

I don't know if it's more appropriate to remove the uppercasing entirely (I don't know what it's supposed to be uppercasing) or to change the selector of the rule so it isn't affecting these type hints.

@jakelishman jakelishman added the bug Something isn't working label Mar 2, 2023
@HuangJunye HuangJunye added the needs triage Needs further discussion and prioritisation label Mar 6, 2023
@Eric-Arellano Eric-Arellano added this to the Theme v12.0.0 milestone Apr 3, 2023
@javabster
Copy link
Collaborator

The property you mention here is also responsible for capitalising the class title at the top of the page, so probably can't remove it completely, I'll have a look at some of the other css attributes around and see what makes the most sense
Screenshot 2023-05-11 at 2 45 19 PM

Eric-Arellano pushed a commit that referenced this issue May 11, 2023
fixes #194 

I didn't test locally as we don't have any classes that use the
`@dataclasses.dataclass` decorator yet, but I validated the changes
using the inspect tool on
https://qiskit.org/documentation/stable/0.41/stubs/qiskit.algorithms.optimizers.OptimizerState.html

I opted to just force those specific properties that live under the
Attributes section to be capitalized., instead of removing the uppercase
setting at the higher level, as that uppercase setting is used for the
main CLASS header at the top of the page.

Before:
<img width="1013" alt="Screenshot 2023-05-11 at 2 53 40 PM"
src="https://github.com/Qiskit/qiskit_sphinx_theme/assets/23662430/2f12b3ee-f7c0-4838-96c3-ca98f0a91ac6">

After:

<img width="915" alt="Screenshot 2023-05-11 at 3 20 44 PM"
src="https://github.com/Qiskit/qiskit_sphinx_theme/assets/23662430/b08629a6-05e9-4e63-b7f3-713c5cdcd5b3">
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working needs triage Needs further discussion and prioritisation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants