Code-Text Styling Consistency

[smeragoel]

Context

I am opening this ticket for internally discussing the styling inconsistency in code-text, based on the issues raised in pydata/pydata-sphinx-theme#1852. The goal is to gather thoughts, suggestions, and feedback before posting final recommendations to the original issue.

Documentation

I have created a document outlining the current issues and proposed changes. It includes detailed examples and comparisons with other industry standards. Link to Document: Code-Text Styling Consistency

This document is intended for easy reference and detailed explanations, because large tables and detailed descriptions can be difficult to read and write in GitHub comments. I will summarize the discussion points and action items from this document and post them here once finalized.

Figma Designs

I've also created some designs to illustrate proposed changes: Figma Design

[smeragoel]

Based on today's discussion. here are the 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.

[smeragoel]

I've also added the summarised findings to the original issue: pydata/pydata-sphinx-theme#1852 (comment)