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 #34134435 | 📁 Comparing 4a8dd39 against latest (f0d30cc)

  🔍 Preview build  

69 files changed · ± 69 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 59 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!