Consistent use of monospaced font

[mdhaber]

I think it would be helpful if code tokens were consistently rendered in monospaced font. For instance, in the documentation of scipy.stats.bootstrap, text that refers to code is rendered in many different styles.

1. The navigation pane uses proportional font:

2. The scipy.stats table of contents mixes monospaced and proportional font in the function signature:

3. In the scipy.stats.bootstrap page, the title heading uses proportional font:

4. The signature is all monospaced and bold, but some is italicized and some is not:

5. Parameters of the function enclosed in single backticks appear in proportional font with emphasis:

(Although this situation may be improved by numpy/numpydoc#525 and linked issues.)

6. Double backticks result in monospaced font with a gray background and pink text:

7. The names of parameters in the parameter descriptions use bold, proportional font:

8. The type descriptions use bold, italicized, proportional font; double backticks can be used for additional stylization:

(Please feel free to add other ways that code appears. I think that the numbers will help us refer to distinct cases as needed.)

This issue could be generalized to be about consistent use of color, boldface, italics, etc..., but I thought it would be best to be a little more targeted here. So my suggestion is that that appearances of code should either all be monospaced or all proportional. My initial motivation is from the perspective of consistency and aesthetics, but I think there is also an accessibility perspective to be considered. Personally, I think that monospacing is a helpful visual cue to distinguish code from other text, so I would prefer that all code be monospaced, but I recognize that there may be arguments in the other direction.

[melissawm]

See scipy/scipy#20890

[trallard]

Hey folks. I know some variation across style weight, colour is intentional (albeit not perfectly executed) to visually differentiate functions from params and the likes.

However I agree there are other further inconsistencies and overall improvements we can make to end up with a more coherent style.

Tagging @isabela-pf and @smeragoel for visibility and so that we can add this to our design backlog

[smeragoel]

Thank you for bringing this up! After researching various ways to address this issue and conducting thorough internal discussions, we’ve come up with the following final recommendations:

S.no	Category	Description	Example Pages / Links on PyData Sphinx Theme	Current Text Formatting	Recommendation / Discussion
A.	Navigation Pane	This refers to the headings in the Section Navigation on the left side of the webpage.	Section Navigation	Proportional	We should switch to Monospace. This is a recurring design pattern in other documentation themes and will help in clear identification of code-text.
B.	Table of Contents	Function signatures in ToC	Functions ToC	Monospace, Proportional	All text in the function signature should be monospaced. This includes function name, parameters, kwargs, type annotation, default values etc.
C.	Title Heading	Main headings on documentation pages which contain code-text.	Title Heading	Proportional	Code-text in headings should be monospaced, but normal text should be proportional. Also, code-text should not wrap or break. Example: 1. Heading with normal and code-text: This is a page about math.h 2. Heading with just code-text: math.h
D.	Function Signature	Representation of function names and parameters.	Function Signature	Monospace, bold, italic	This code text is very busy visually so we should simplify the text formatting. Here’s the redesigned function signature: Figma Design
E.	Parameter names in descriptions	Descriptions of function parameters.	Parameter Descriptions	Proportional, bold	Description text will remain proportional.
F.	Parameter Type	Description of parameter data types	Parameter Type	Proportional, italics	Description text will remain proportional.
G.	Function Source Link	Source link to the original function headers	Function Source Link	Monospace, bold	Source link does not refer to code text, and should be treated as a normal link and should be proportional text.

The most significant changes are in the function signature and definition formatting (D - G):

1. Class name is no longer bold.
2. Parameters now use a muted text color.
3. Default values are not bold and are displayed in green.
4. Type annotations are no longer bold and are shown in blue.
5. The source link text is proportional and no longer bold.
6. The heading text for parameters, returns, and return types now has a muted color.
7. Padding between paragraphs has been increased for better readability.

I’ve also prepared a document outlining the findings and discussion points in more detail, including a heavy table that couldn’t be rendered properly in md: Code-Text Styling Consistency Findings

Looking forward to hearing your thoughts and feedback!

[mdhaber]

Thanks for working on this!

Do I understand that at the "Figma Design" page, "Current Screenshot" is what we have now, and "Template" is the proposed design?

---

In the Code-Text Styling Consistency Findings, I see in the "Discussion" (emphasis yours):

1. Should parameters be monospaced or proportional? Parameters are currently being styled differently for different locations. For consistency, we should ensure a similar text treatment. My recommendation would be to use monospaced parameters, to ensure clarity and consistency and make it easy for users to differentiate between code and regular text.

and

3. My understanding about parameters data type (int, list, str) is that it is code text and hence should be monospaced

I think these are referring to items E and F in the table above, but I'm not sure what the conclusion was for those. It says "Description text will remain proportional" (emphasis mine), which I would certainly agree with, but it does not mention the parameters (code) themselves or types (code) specifically. What was the conclusion about the formatting of parameter names and types?

[trallard]

Do I understand that at the "Figma Design" page, "Current Screenshot" is what we have now, and "Template" is the proposed design?

That is correct.

I think these are referring to items E and F in the table above, but I'm not sure what the conclusion was for those. It says "Description text will remain proportional" (emphasis mine), which I would certainly agree with, but it does not mention the parameters (code) themselves or types (code) specifically. What was the conclusion about the formatting of parameter names and types?

Parameters, types, and descriptions will be in proportional font, as indicated in the table above; this is also presented in the Figma parameters subsection:

[mdhaber]

Right, I saw the table refered to the description text, but thanks for clarifying that the code (parameter name and types) would also be in proportional font. I see in the discussion that proportional font is used for these parts in some other themes (Furo and Read the Docs) - was that the deciding factor against the preliminary recommendation?

[smeragoel]

Thanks for your questions @mdhaber!

While usage patterns definitely play an important role in this decision, the deciding factor was that descriptions are not meant to contain copy-paste code. Code-text, by contrast, indicates something that users can copy and paste directly into their code. That distinction is why we opted for proportional fonts in descriptions.