Add RTL support to python-docs-theme by sepehr-rs · Pull Request #324 · python/python-docs-theme

sepehr-rs · 2026-08-17T17:26:26Z

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!

for more information, see https://pre-commit.ci

read-the-docs-community · 2026-08-17T18:47:50Z

Documentation build overview

📚 python-docs-theme-previews | 🛠️ Build #34134435 | 📁 Comparing 4a8dd39 against latest (f0d30cc)

🔍 Preview build

69 files changed · ± 69 modified

± Modified

StanFromIreland · 2026-08-17T19:51:58Z

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 · 2026-08-18T02:57:32Z

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 · 2026-08-18T08:59:57Z

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

I'd prefer that, personally.

StanFromIreland · 2026-08-18T10:16:40Z

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

StanFromIreland · 2026-08-18T16:58:17Z

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 · 2026-08-18T17:02:07Z

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

Breaks RTL outright

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.

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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

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.

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 · 2026-08-18T17:04:58Z

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

for more information, see https://pre-commit.ci

sepehr-rs · 2026-08-19T09:22:13Z

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 · 2026-08-19T20:40:51Z

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 · 2026-08-19T20:47:34Z

@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 · 2026-08-19T21:08:27Z

+    context: dict[str, Any],
+    doctree: None,
+) -> None:
+    language = app.config.language or "en"


Why not context["language"]?

StanFromIreland · 2026-08-19T21:08:42Z

 MESSAGE_CATALOG_NAME = "python-docs-theme"


+def _tobool(val: object) -> bool:


This seems quite overcomplicated for something used once.

StanFromIreland · 2026-08-19T21:09:52Z

+
+    content_root = context.get("content_root", "")
+    lang_part = f' lang="{escape(language)}"' if language is not None else ""
+    context["html_tag"] = Markup(


I'm not a fan of this, what if Sphinx adds an attribute?

StanFromIreland · 2026-08-19T21:11:06Z


 div.body {
-    padding: 0 0 0 1.2em;
+    padding-inline-start: 1.2em;


This no longer zeros the other sides:

https://github.com/sphinx-doc/sphinx/blob/e44a40eb2f810558ccd9da1425421270ccb81351/sphinx/themes/classic/static/classic.css.jinja#L40

StanFromIreland · 2026-08-19T21:11:41Z

    padding: 0.3em 0.6em;
    font-size: 90%;
    color: #333;
-


These are unrelated changes.

StanFromIreland · 2026-08-19T21:11:54Z


-dl > dt span ~ em,
-.sig {
-    font-family: Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace;


Why are we dropping the font?

StanFromIreland · 2026-08-19T21:12:17Z

 div.footer {
    line-height: 150%;
-    text-align: right;
+    text-align: end; /* was: text-align: right */


Suggested change

text-align: end; /* was: text-align: right */

text-align: end;

These comments don't add any useful information.

StanFromIreland · 2026-08-19T21:13:28Z


 from pathlib import Path

+from markupsafe import Markup, escape


This is now an undeclared direct dependency...

sepehr-rs and others added 5 commits August 17, 2026 19:22

Add is_rtl flag to theme.toml

091917c

Force RTL but keep codeboxes LTR

e2cc426

Add Vazirmatn support

5870154

Fix sidebar

6eb161f

[pre-commit.ci] auto fixes from pre-commit.com hooks

13de683

for more information, see https://pre-commit.ci

sepehr-rs marked this pull request as draft August 17, 2026 17:30

Fix siderbar

1ce690e

Fix navbar

09fce2b

sepehr-rs marked this pull request as ready for review August 18, 2026 04:04

StanFromIreland mentioned this pull request Aug 18, 2026

Add Persian translation python/docsbuild-scripts#351

Open

Remove Vazirmatn support

a9ec66e

StanFromIreland mentioned this pull request Aug 18, 2026

Add Persian (fa) translation to python docs theme #322

Merged

Merge branch 'python:main' into add-rtl

779f8b9

StanFromIreland reviewed Aug 18, 2026

View reviewed changes

Comment thread python_docs_theme/static/pydoctheme.css

Bring back CSS attributes for code-block-caption

e9a4b29

sepehr-rs and others added 2 commits August 19, 2026 12:45

Address review comments

a4d0f82

[pre-commit.ci] auto fixes from pre-commit.com hooks

4a8dd39

for more information, see https://pre-commit.ci

StanFromIreland requested review from JulienPalard and hugovk August 19, 2026 20:42

StanFromIreland reviewed Aug 19, 2026

View reviewed changes

StanFromIreland requested a review from picnixz August 19, 2026 21:17

		MESSAGE_CATALOG_NAME = "python-docs-theme"


		def _tobool(val: object) -> bool:

	text-align: end; /* was: text-align: right */
	text-align: end;


		from pathlib import Path

		from markupsafe import Markup, escape

Uh oh!

Uh oh!

Conversation

sepehr-rs commented Aug 17, 2026

Uh oh!

read-the-docs-community Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

StanFromIreland commented Aug 17, 2026

Uh oh!

sepehr-rs commented Aug 18, 2026

Uh oh!

StanFromIreland commented Aug 18, 2026

Uh oh!

StanFromIreland commented Aug 18, 2026

Uh oh!

Uh oh!

StanFromIreland commented Aug 18, 2026

Uh oh!

StanFromIreland commented Aug 18, 2026

Uh oh!

sepehr-rs commented Aug 18, 2026

Uh oh!

sepehr-rs commented Aug 19, 2026

Uh oh!

StanFromIreland commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland commented Aug 19, 2026

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

read-the-docs-community Bot commented Aug 17, 2026 •

edited

Loading

StanFromIreland commented Aug 19, 2026 •

edited

Loading