Add RTL support to python-docs-theme

[sepehr-rs]

Added RTL support to python-docs-theme. Passing the is_rtl=true flag when building the documentation now generates RTL-friendly pages.
I also added Vazirmatn as the font for RTL scripts (it really improves readability), but I’m not sure how acceptable this is, so I’m happy to change it if the maintainers disagree.
Please let me know if any changes or additions are needed. Thanks in advance!

[read-the-docs-community]

Documentation build overview

📚 python-docs-theme-previews | 🛠️ Build #34156553 | 📁 Comparing 893d844 against latest (f0d30cc)

  🔍 Preview build  

74 files changed · ± 74 modified

± Modified

• contents.html
• download.html
• genindex-B.html
• genindex-C.html
• genindex-E.html
• genindex-H.html
• genindex-I.html
• genindex-P.html
• genindex-R.html
• genindex-S.html
• and 64 more...

[StanFromIreland]

I think it's better to do the font in a follow up, since I have some concerns about licensing and such things.

[sepehr-rs]

I think it's better to do the font in a follow up, since I have some concerns about licensing and such things.

Although I’m okay with leaving this for a follow-up, Vazirmatn is an open-source project, licensed under the SIL Open Font License. But if you still think this is better handled in a follow-up, I’ll do that. Thanks a lot!

[StanFromIreland]

But if you still think this is better handled in a follow-up

I'd prefer that, personally.

[StanFromIreland]

Can you please update your branch to pull in the translation?

[StanFromIreland]

Some observations:

The hamburger on the mobile view is on the wrong side.

Function signatures are still LTR, but on the right side?

Inline function references are LTR, but have the parentheses on the RTL side.

Similar to previous point.

On English pages, the text is also now LTR. Is this alright from your perspective? I think Sphinx now has some tags to differentiate translated messages, so we could avoid this if necessary.

There's now a white artefact beside the sidebar?

[StanFromIreland]

Also, I tried to get Claude to look at this. Here's its analysis:

Breaks RTL outright

1. Mobile nav double-reverses — pydoctheme.css:632, :694
   In a direction: rtl container a plain flex-direction: row already lays out right-to-left. Adding row-reverse flips it back, and .toggler__label { order: 1 } drops the hamburger at the far left. Net result: the mobile header renders in exactly the LTR arrangement the PR set out to mirror. Delete both rules.

2. Search icon vs. its gutter — :663, :679
   Line 657 correctly converts padding-left: 24px → padding-inline-start. Lines 662–664 then set inline-start: 4px; inline-end: 24px, whose used values are identical to the original physical rule. But the magnifier svg is position: absolute with no inset, so it falls at its static position — main-start, i.e. the right edge in RTL. Icon right, 24px gutter left, placeholder text under the icon.

3. 230px phantom gutter on RTL desktop — :179
   div.bodywrapper { margin-inline-start: 0 } maps to margin-right in RTL, so classic's margin: 0 0 0 230px (classic.css_t:41, sidebarwidth=230) survives untouched. Every RTL desktop page ≥1024px gets dead space left and the sidebar right. The removed margin-left: min(25vw,350px) used to cover both. Use margin: 0.

Unmirrored / ineffective

4. direction: ltr is a no-op on inline code — :266
   Per CSS, direction applies to an inline box only when unicode-bidi isn't normal. It works for the block-level pre/.highlight, but inline literals like os.path.join(a, b) still get bidi-reordered. Needs unicode-bidi: isolate alongside.

5. API signatures missed entirely — :265
   Sphinx emits signatures as

   with — no pre, no code, no .highlight. So os.path.join(path, *paths) renders with mirrored parens and reordered params. .sig, dl > dt, .sig-param need the same treatment.

6. RTL rule out-specifies the mobile override — :241
   html[dir='rtl'] div.body is (0,2,2); the @media (max-width:1023px) { div.body { padding: 0 } } at :566 is (0,1,1) and media queries add no specificity, so RTL wins regardless of order — 1.2em of padding on a min-width: 100% element, i.e. overflow. LTR is unaffected, so it's an RTL-only asymmetry. padding-inline-start on the base rule avoids the extra selector.

7. Leftovers: .menu { padding: … 20px } (:758) unconverted; div.sphinxsidebar ul ul { margin-left: 20px } (basic.css) never overridden, so RTL toctree indents away from parents; dl.field-list > dt padding unmirrored.

8. Inline style beats every stylesheet — layout.html:9
   style="margin-right: 10px" on the first li.right. The PR floats these left in RTL, so the gap lands between items instead of at the edge. → margin-inline-end.

Design-level

9. RTL is JS-only — layout.html:85
   Mutating documentElement.dir client-side means JS-disabled → fully LTR, a hard failure rather than degraded styling. This theme already has an html-page-context handler (init.py:22) that can set html_tag server-side, and derive RTL from config.language (ar, he, fa, ur) instead of a second option that can silently disagree with it.

10. theme_is_rtl|lower == "true" — layout.html:83
    Reimplements Sphinx's tobool filter, more narrowly. {"is_rtl": "1"} or "yes" — both idiomatic — silently do nothing. Use |tobool.

11. Float-based breadcrumbs — :128
    div.related li { display: inline } already mirrors for free under direction: rtl. Floating computes display: block, killing the collapsible whitespace (hence the compensating padding-inline, which then also hits li.right), and breaks .switchers' inline-flex.

12. transition: inset-inline-start 400ms — :744
    An unrecognised transition-property invalidates the whole shorthand, so the menu snaps instead of sliding — and it's not RTL-gated, so LTR builds are exposed too. Animating an inset also forces layout per frame; transform: translateX() composites.

Unrelated regression

13. div.code-block-caption lost all seven declarations — :286
    Not an RTL change. With the override gone, classic's { color: #efefef; background-color: #1c4e63 } wins — captions become dark-blue bars instead of the theme's grey box, no border, no radius, no padding. The surviving & + div pre { border-top-*-radius: 0 !important } then squares off a code block under a caption with no matching box, and dark mode's border-color: #616161 is inert with no border-style declared. Looks accidental.

14. Dead code — div.document { flex-direction: row } (:146) is the initial value; .mobile-nav { inset-inline-start: 0 } (:610) is inert. Four /* was: … / comments annotate 4 of ~25 conversions at random, and one replaced / follows div.body pre */, which documented a real cross-rule colour dependency.

[sepehr-rs]

Thanks so much for the thorough review! I’ll work through these comments and send a patch soon.

[sepehr-rs]

Hi @StanFromIreland, I addressed the review comments you left with Claude's help, built the docs locally to verify the changes, and all the issues you pointed out appear to be resolved. I also checked that the LTR version remains unaffected.
Please let me know if anything else needs adjustment. Thanks again for the thorough review!

[StanFromIreland]

I also checked that the LTR version remains unaffected.

Indeed, testing with the current patch, the only change is the addition of dir="ltr" attribute:

A selection of pages

diff --git a/html/whatsnew/changelog.html b/base/html/whatsnew/changelog.html
index 903b246..c60dcd2 100644
--- a/html/whatsnew/changelog.html
+++ b/base/html/whatsnew/changelog.html
@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 
-<html lang="en" data-content_root="../">
+<html lang="en" dir="ltr" data-content_root="../">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -20,7 +20,7 @@
     
     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
     <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
-    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
+    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=83ab0a67" />
     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
     
     <script src="../_static/documentation_options.js?v=d86cccaa"></script>
@@ -50462,7 +50462,7 @@ Kilburn.</p></li>
 <a href="https://www.python.org/psf/donations/">Please donate.</a>
 <br>
     <br>
-      Last updated on Aug 19, 2026 (20:32 UTC).
+      Last updated on Aug 19, 2026 (20:30 UTC).
     
       <a href="/bugs.html">Found a bug</a>?

diff --git a/html/library/sqlite3.html b/base/html/library/sqlite3.html
index 6decdde..fc9f358 100644
--- a/html/library/sqlite3.html
+++ b/base/html/library/sqlite3.html
@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 
-<html lang="en" data-content_root="../">
+<html lang="en" dir="ltr" data-content_root="../">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -20,7 +20,7 @@
     
     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
     <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
-    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
+    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=83ab0a67" />
     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
     
     <script src="../_static/documentation_options.js?v=d86cccaa"></script>
@@ -2979,7 +2979,7 @@ statements.  This is no longer the case.</p>
 <a href="https://www.python.org/psf/donations/">Please donate.</a>
 <br>
     <br>
-      Last updated on Aug 19, 2026 (20:32 UTC).
+      Last updated on Aug 19, 2026 (20:30 UTC).
     
       <a href="/bugs.html">Found a bug</a>?

diff --git a/html/library/datetime.html b/base/html/library/datetime.html
index b32b4a9..0381fa5 100644
--- a/html/library/datetime.html
+++ b/base/html/library/datetime.html
@@ -1,6 +1,6 @@
 <!DOCTYPE html>
 
-<html lang="en" data-content_root="../">
+<html lang="en" dir="ltr" data-content_root="../">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -20,7 +20,7 @@
     
     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
     <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
-    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
+    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=83ab0a67" />
     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
     
     <script src="../_static/documentation_options.js?v=d86cccaa"></script>
@@ -3649,7 +3649,7 @@ for a good explanation.</p>
 <a href="https://www.python.org/psf/donations/">Please donate.</a>
 <br>
     <br>
-      Last updated on Aug 19, 2026 (20:32 UTC).
+      Last updated on Aug 19, 2026 (20:30 UTC).
     
       <a href="/bugs.html">Found a bug</a>?

[StanFromIreland]

@cben, maybe you can help review this? From what I gather you're the expert in this area, I'd appreciate your thoughts here.

[StanFromIreland]

I'm a little worried about regressing LTR, we should be very careful here.

Would something in layout.html like:

{% block body_tag %}<body{% if theme_is_rtl|tobool %} dir="rtl"{% endif %}>{% endblock %}

not work instead of add_html_dir_to_context?

[StanFromIreland]

These are unrelated changes.

[StanFromIreland]

I still see these as removed.

[sepehr-rs]

Okay, I tried fixing these by adding spaces in place of the removed whitespace, but I don't know if this has fixed the problem or not. Could this be a quirk on GitHub's side?

[sepehr-rs]

Thanks a lot for the review! I addressed your review comments, but for the whitespace changes, they don't show up anymore on my code editor, so I hope they're resolved. Please let me know if any changes are needed :)

[cben]

@StanFromIreland Ooh I'll be glad to review but have family events & vacations for a week, not sure worth waiting for me but I can review post-merge too.

[StanFromIreland]

I've created #325 to get RtD previews with an RTL build.

[StanFromIreland]

@StanFromIreland Ooh I'll be glad to review but have family events & vacations for a week, not sure worth waiting for me but I can review post-merge too.

That would be great!

[StanFromIreland]

I still see these as removed.