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

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

Documentation build overview

📚 python-docs-theme-previews | 🛠️ Build #34221298 | 📁 Comparing 1923a64 against latest (f0d30cc)

🔍 Preview build

85 files changed · + 1 added · ± 84 modified

+ Added

library/time-complexity.html

± Modified

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

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!

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

I'd prefer that, personally.

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

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

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!

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>?

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

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?

…o layout.html

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 :)

@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.

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

@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!

Oh sorry, I meant to push to #325.

This reverts commit 074cb15.

Please update the README for this option.

Co-authored-by: Stan Ulbrych <stan@python.org>

Thanks a lot for the review! I addressed your comments, please let me know if any other changes are needed.

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

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

This comment was marked as resolved.

Sign in to view

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

sepehr-rs added 2 commits August 20, 2026 08:08

Remove add_html_dir_to_context from __init__ and move RTL detection t…

64a25de

…o layout.html

Update pydoctheme.css

9a9dcab

StanFromIreland reviewed Aug 20, 2026

View reviewed changes

Comment thread python_docs_theme/static/pydoctheme.css Outdated

Comment thread python_docs_theme/static/pydoctheme.css

Comment thread python_docs_theme/static/pydoctheme.css

sepehr-rs and others added 3 commits August 20, 2026 18:22

Address review comments

7fc51b8

Fix whitespace changes

893d844

Build Farsi in RTD

074cb15

Revert "Build Farsi in RTD"

06cf519

This reverts commit 074cb15.

StanFromIreland reviewed Aug 24, 2026

View reviewed changes

Comment thread python_docs_theme/static/pydoctheme.css

Comment thread python_docs_theme/static/pydoctheme.css Outdated

Comment thread python_docs_theme/static/pydoctheme.css Outdated

Comment thread python_docs_theme/static/pydoctheme.css Outdated

sepehr-rs and others added 2 commits August 25, 2026 07:39

Apply suggestion from @StanFromIreland

2c55d7d

Co-authored-by: Stan Ulbrych <stan@python.org>

Address review comments

9c41b1f

pre-commit-ci Bot and others added 2 commits August 25, 2026 05:01

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

e23b0a8

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

Update README.md

1923a64

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

Uh oh!

Uh oh!

Add RTL support to python-docs-theme - #324

Add RTL support to python-docs-theme#324sepehr-rs wants to merge 22 commits intopython:mainpython/python-docs-theme:mainfrom sepehr-rs:add-rtlsepehr-rs/python-docs-theme:add-rtlCopy head branch name to clipboard

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!

This comment was marked as resolved.

This comment was marked as resolved.

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sepehr-rs commented Aug 20, 2026

Uh oh!

cben commented Aug 20, 2026

Uh oh!

StanFromIreland commented Aug 20, 2026

Uh oh!

StanFromIreland commented Aug 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland commented Aug 24, 2026

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sepehr-rs commented Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add RTL support to python-docs-theme#324
sepehr-rs wants to merge 22 commits into
python:mainfrom
sepehr-rs:add-rtl

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

StanFromIreland commented Aug 19, 2026 •
edited
Loading