search

Quansight-Labs / czi-scientific-python-mgmt

🐍 Top level project management for Scientific-Python CZI grant at Labs
https://github.com/orgs/Quansight-Labs/projects/11?query=is%3Aopen+sort%3Aupdated-desc
BSD 3-Clause "New" or "Revised" License
4 stars 1 forks source link

Code-Text Styling Consistency #111

Open smeragoel opened 1 month ago

smeragoel commented 1 month ago

Context

I am opening this ticket for internally discussing the styling inconsistency in code-text, based on the issues raised in https://github.com/pydata/pydata-sphinx-theme/issues/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 commented 1 month ago

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 commented 3 weeks ago

I've also added the summarised findings to the original issue: https://github.com/pydata/pydata-sphinx-theme/issues/1852#issuecomment-2312184516