Add RTL support 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 #34640845 | 📁 Comparing 55e8f5a against latest (f0d30cc)

🔍 Preview build

429 files changed · + 9 added · ± 419 modified · - 1 deleted

+ Added

± Modified

- Deleted

library/dialog.html

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.

@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

And some additional observations, footnotes and search results are still LTR:

Hey @sepehr-rs, just checking in. Some changes are still pending, and I'd love to land this to unblock the Persian translation. Happy to help if anything is unclear.

Also a little ping for @cben, I'd like to hear what you think. :-)

Hi @StanFromIreland, sorry for the delay on this. I recently found a free API and ended up translating the entire Python documentation corpus into Persian (this PR) and what I initially thought would be a 3-day plan turned into a 3-week project 😬.
But it’s now in the final stages of cleanup and review, so I’ll try to get back to this today or tomorrow. Thanks a lot for following up with me, I really appreciate it!

Thanks a lot for your review and patience!
I’ve addressed your review comments. Please let me know if any further changes are needed.

Overall looks good to me, last few little comments.

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

Thanks for the additional review! Let me know if anything else needs changing.

Please don't force push in the future, it makes reviewing more difficult.

LGTM

@hugovk, could you please take a look?

Exciting!

@StanFromIreland Release when ready!

Merged, thank you @sepehr-rs !

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

Merged

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

StanFromIreland reviewed Aug 26, 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 README.md Outdated

StanFromIreland changed the title Add RTL support to python-docs-theme Add RTL support Aug 26, 2026

Address reviews

6d36814

StanFromIreland reviewed Sep 18, 2026

View reviewed changes

Comment thread README.md 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 September 18, 2026 21:48

Apply suggestion from @StanFromIreland

2263680

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

Address review comments

55e8f5a

sepehr-rs force-pushed the add-rtl branch 2 times, most recently from 61fe270 to 55e8f5a Compare September 18, 2026 18:26

StanFromIreland approved these changes Sep 18, 2026

View reviewed changes

hugovk approved these changes Sep 18, 2026

View reviewed changes

StanFromIreland merged commit 0ca52a5 into python:main Sep 18, 2026
25 checks passed

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

Repository navigation

Add RTL support - #324

Add RTL support#324StanFromIreland merged 25 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 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!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland commented Sep 13, 2026

Uh oh!

sepehr-rs commented Sep 14, 2026

Uh oh!

sepehr-rs commented Sep 18, 2026

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sepehr-rs commented Sep 18, 2026

Uh oh!

StanFromIreland commented Sep 18, 2026

Uh oh!

StanFromIreland left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

StanFromIreland commented Sep 18, 2026

Uh oh!

Add RTL support#324
StanFromIreland merged 25 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

StanFromIreland left a comment •
edited
Loading