Skip to content

Commit 6dc493c

Browse files
Copilotmmcky
Copilot
and
mmcky
committed
Complete RTL script support implementation with tests and documentation
Co-authored-by: mmcky <8263752+mmcky@users.noreply.github.com>
1 parent 8420750 commit 6dc493c

4 files changed

Lines changed: 438 additions & 0 deletions

File tree

‎docs/RTL_SUPPORT.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# RTL (Right-to-Left) Script Support
2+
3+
The QuantEcon Book Theme now supports RTL (Right-to-Left) scripts including Arabic, Hebrew, Persian, and other RTL languages.
4+
5+
## Usage
6+
7+
To enable RTL support in your Sphinx configuration, add the following to your `conf.py`:
8+
9+
```python
10+
html_theme = "quantecon_book_theme"
11+
12+
html_theme_options = {
13+
"script_right_to_left": True, # Enable RTL support
14+
# ... other theme options
15+
}
16+
```
17+
18+
## Configuration
19+
20+
- **Option**: `script_right_to_left`
21+
- **Type**: Boolean
22+
- **Default**: `False`
23+
- **Description**: When set to `True`, enables right-to-left text direction and adjusts the entire layout for RTL languages.
24+
25+
## Features
26+
27+
When RTL mode is enabled, the theme automatically adjusts:
28+
29+
### Layout Changes
30+
- **Text Direction**: All text flows from right to left
31+
- **Sidebar Position**: Moves from left to right side
32+
- **Navigation**: Toolbar elements are reversed for RTL flow
33+
- **Margins and Padding**: Adjusted for RTL reading patterns
34+
- **Blockquotes**: Border appears on the right side instead of left
35+
36+
### Preserved Elements
37+
For optimal readability, these elements remain in LTR (Left-to-Right) direction:
38+
- **Code blocks** and syntax highlighting
39+
- **Mathematical equations** and formulas
40+
- **URLs** and technical content
41+
42+
## Example
43+
44+
```python
45+
# conf.py for an Arabic documentation site
46+
project = "دليل البرمجة"
47+
language = "ar" # Arabic language code
48+
49+
html_theme = "quantecon_book_theme"
50+
html_theme_options = {
51+
"script_right_to_left": True,
52+
"repository_url": "https://github.com/your-repo/arabic-docs",
53+
# ... other options
54+
}
55+
```
56+
57+
## Supported Languages
58+
59+
This RTL implementation supports all RTL scripts including:
60+
- **Arabic** (العربية)
61+
- **Hebrew** (עברית)
62+
- **Persian/Farsi** (فارسی)
63+
- **Urdu** (اردو)
64+
- **Pashto** (پښتو)
65+
- And other RTL writing systems
66+
67+
## Testing
68+
69+
You can test the RTL functionality by:
70+
71+
1. Setting `script_right_to_left = True` in your theme options
72+
2. Building your Sphinx documentation
73+
3. Viewing the generated HTML to see the RTL layout adjustments
74+
75+
The theme includes comprehensive test files demonstrating both LTR and RTL modes side by side.
76+
77+
## Implementation Details
78+
79+
- RTL styles are implemented using CSS `[dir="rtl"]` selectors
80+
- The `dir="rtl"` attribute is conditionally added to the `<body>` element
81+
- Layout adjustments use CSS flexbox and positioning for proper RTL flow
82+
- All changes are backward compatible with existing LTR documents

‎tests/ltr_vs_rtl_comparison.html‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>LTR vs RTL Comparison</title>
7+
<link rel="stylesheet" href="../../../src/quantecon_book_theme/theme/quantecon_book_theme/static/styles/quantecon-book-theme.css">
8+
<style>
9+
.comparison {
10+
display: flex;
11+
gap: 20px;
12+
margin: 20px;
13+
}
14+
.test-section {
15+
flex: 1;
16+
border: 2px solid #ccc;
17+
padding: 20px;
18+
background: #f9f9f9;
19+
}
20+
.test-section h3 {
21+
margin-top: 0;
22+
color: #0072bc;
23+
text-align: center;
24+
}
25+
body {
26+
margin: 0;
27+
padding: 0;
28+
}
29+
</style>
30+
</head>
31+
<body>
32+
<h1 style="text-align: center; margin: 20px;">QuantEcon Book Theme: LTR vs RTL Comparison</h1>
33+
34+
<div class="comparison">
35+
<!-- LTR Section -->
36+
<div class="test-section">
37+
<h3>LTR Mode (Default)</h3>
38+
<div class="qe-wrapper">
39+
<div class="qe-main">
40+
<div class="qe-page">
41+
<div class="qe-page__header">
42+
<div class="qe-page__header-copy">
43+
<p class="qe-page__header-heading">English Book</p>
44+
<p class="qe-page__header-subheading">Testing Left-to-Right Layout</p>
45+
</div>
46+
</div>
47+
48+
<div class="qe-page__content">
49+
<h2>English Content</h2>
50+
<p>This is a test of normal left-to-right text flow. The sidebar should be on the left, and text should align to the left.</p>
51+
52+
<blockquote>
53+
<p>This is a blockquote in English. The border should be on the left side.</p>
54+
</blockquote>
55+
56+
<pre><code>def example():
57+
return "Hello World"</code></pre>
58+
</div>
59+
</div>
60+
61+
<div class="qe-sidebar">
62+
<div class="qe-sidebar__header">Contents</div>
63+
<nav class="qe-sidebar__nav">
64+
<ul>
65+
<li><a href="#section1">Section 1</a></li>
66+
<li><a href="#section2">Section 2</a></li>
67+
</ul>
68+
</nav>
69+
</div>
70+
</div>
71+
72+
<div class="qe-toolbar">
73+
<div class="qe-toolbar__inner">
74+
<ul>
75+
<li><a href="#">Home</a></li>
76+
<li><a href="#">Search</a></li>
77+
</ul>
78+
<ul>
79+
<li><a href="#">Download</a></li>
80+
<li><a href="#">Share</a></li>
81+
</ul>
82+
</div>
83+
</div>
84+
</div>
85+
</div>
86+
87+
<!-- RTL Section -->
88+
<div class="test-section" dir="rtl">
89+
<h3>RTL Mode (script_right_to_left = True)</h3>
90+
<div class="qe-wrapper">
91+
<div class="qe-main">
92+
<div class="qe-page">
93+
<div class="qe-page__header">
94+
<div class="qe-page__header-copy">
95+
<p class="qe-page__header-heading">كتاب عربي</p>
96+
<p class="qe-page__header-subheading">اختبار تخطيط من اليمين إلى اليسار</p>
97+
</div>
98+
</div>
99+
100+
<div class="qe-page__content">
101+
<h2>محتوى عربي</h2>
102+
<p>هذا اختبار لتدفق النص الطبيعي من اليمين إلى اليسار. يجب أن يكون الشريط الجانبي على اليمين، ويجب أن يكون النص محاذاة إلى اليمين.</p>
103+
104+
<blockquote>
105+
<p>هذا اقتباس باللغة العربية. يجب أن تكون الحدود على الجانب الأيمن.</p>
106+
</blockquote>
107+
108+
<pre><code>def example():
109+
return "مرحبا بالعالم"</code></pre>
110+
</div>
111+
</div>
112+
113+
<div class="qe-sidebar">
114+
<div class="qe-sidebar__header">المحتويات</div>
115+
<nav class="qe-sidebar__nav">
116+
<ul>
117+
<li><a href="#section1">القسم 1</a></li>
118+
<li><a href="#section2">القسم 2</a></li>
119+
</ul>
120+
</nav>
121+
</div>
122+
</div>
123+
124+
<div class="qe-toolbar">
125+
<div class="qe-toolbar__inner">
126+
<ul>
127+
<li><a href="#">الرئيسية</a></li>
128+
<li><a href="#">البحث</a></li>
129+
</ul>
130+
<ul>
131+
<li><a href="#">تنزيل</a></li>
132+
<li><a href="#">مشاركة</a></li>
133+
</ul>
134+
</div>
135+
</div>
136+
</div>
137+
</div>
138+
</div>
139+
140+
<div style="margin: 20px; padding: 20px; background: #e8f4f8; border-radius: 8px;">
141+
<h3>Key Differences to Note:</h3>
142+
<ul>
143+
<li><strong>Text Direction:</strong> LTR flows left-to-right, RTL flows right-to-left</li>
144+
<li><strong>Sidebar Position:</strong> LTR has sidebar on left, RTL has sidebar on right</li>
145+
<li><strong>Blockquote Borders:</strong> LTR has left border, RTL has right border</li>
146+
<li><strong>Code Blocks:</strong> Remain LTR in both modes for better readability</li>
147+
<li><strong>Navigation:</strong> Toolbar elements are reversed in RTL mode</li>
148+
</ul>
149+
</div>
150+
</body>
151+
</html>

‎tests/rtl_test.html‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>RTL Test</title>
7+
<link rel="stylesheet" href="../../../src/quantecon_book_theme/theme/quantecon_book_theme/static/styles/quantecon-book-theme.css">
8+
</head>
9+
<body dir="rtl">
10+
<div class="qe-wrapper">
11+
<div class="qe-main">
12+
<div class="qe-page">
13+
<div class="qe-page__header">
14+
<div class="qe-page__header-copy">
15+
<p class="qe-page__header-heading">كتاب اختبار RTL</p>
16+
<p class="qe-page__header-subheading">اختبار دعم الكتابة من اليمين إلى اليسار</p>
17+
</div>
18+
</div>
19+
20+
<div class="qe-page__content">
21+
<h1>اختبار دعم RTL</h1>
22+
<p>هذا نص تجريبي باللغة العربية لاختبار دعم الكتابة من اليمين إلى اليسار في هذا الموضوع. يجب أن يظهر النص بشكل صحيح مع التوجيه المناسب.</p>
23+
24+
<h2>عبرית</h2>
25+
<p>זהו טקסט לדוגמה בעברית לבדיקת תמיכה בכתיבה מימין לשמאל בנושא זה. הטקסט אמור להיות מוצג כראוי עם הכיוון המתאים.</p>
26+
27+
<h2>Code Block Test</h2>
28+
<p>Code blocks should remain left-to-right:</p>
29+
<pre><code>def hello_world():
30+
return "Hello, World!"</code></pre>
31+
32+
<h2>Math Test</h2>
33+
<p>Mathematical expressions should also remain LTR:</p>
34+
<div class="math">E = mc²</div>
35+
36+
<h2>Table Test</h2>
37+
<table>
38+
<thead>
39+
<tr>
40+
<th>العمود الأول</th>
41+
<th>العمود الثاني</th>
42+
<th>العمود الثالث</th>
43+
</tr>
44+
</thead>
45+
<tbody>
46+
<tr>
47+
<td>البيانات 1</td>
48+
<td>البيانات 2</td>
49+
<td>البيانات 3</td>
50+
</tr>
51+
<tr>
52+
<td>القيمة أ</td>
53+
<td>القيمة ب</td>
54+
<td>القيمة ج</td>
55+
</tr>
56+
</tbody>
57+
</table>
58+
59+
<blockquote>
60+
<p>هذا اقتباس باللغة العربية يجب أن يظهر مع الحدود المناسبة في الجانب الصحيح.</p>
61+
</blockquote>
62+
</div>
63+
</div>
64+
65+
<div class="qe-sidebar">
66+
<div class="qe-sidebar__header">المحتويات</div>
67+
<nav class="qe-sidebar__nav">
68+
<ul>
69+
<li><a href="#section1">القسم الأول</a></li>
70+
<li><a href="#section2">القسم الثاني</a></li>
71+
<li><a href="#section3">القسم الثالث</a></li>
72+
</ul>
73+
</nav>
74+
</div>
75+
</div>
76+
77+
<div class="qe-toolbar">
78+
<div class="qe-toolbar__inner">
79+
<ul>
80+
<li><a href="#">الرئيسية</a></li>
81+
<li><a href="#">البحث</a></li>
82+
</ul>
83+
<ul>
84+
<li><a href="#">تنزيل</a></li>
85+
<li><a href="#">مشاركة</a></li>
86+
</ul>
87+
</div>
88+
</div>
89+
</div>
90+
</body>
91+
</html>

0 commit comments

Comments
 (0)