Add RTL support

AUTHORS.rst

@@ -24,6 +24,7 @@ Contributors
 * Alastair Houghton -- Apple Help builder
 * Alex Gaynor -- linkcheck retry on errors
 * Alexander Todorov -- inheritance_diagram tests and improvements
+* Alireza Shabani -- RTL support
 * Andi Albrecht -- agogo theme
 * Antonio Valentino -- qthelp builder, docstring inheritance
 * Antti Kaihola -- doctest extension (skipif option)

CHANGES.rst

@@ -58,6 +58,9 @@ Features added
   The location of the cache directory must not be relied upon externally,
   as it may change without notice or warning in future releases.
   Patch by Adam Turner.
+* #10385: Add RTL (right-to-left) support for all Sphinx themes via the ``is_rtl``
+  theme option. Includes automatic layout mirroring, and bidirectional text support.
+  Patch by Alireza Shabani.
 
 Bugs fixed
 ----------

doc/usage/theming.rst

@@ -192,6 +192,18 @@ These themes are:
 
     .. versionadded:: 3.2
 
+  - **is_rtl** (true or false): Enable right-to-left (RTL) text direction.
+    Use this for languages that are read right-to-left (like Farsi, Arabic,
+    Hebrew, etc). When enabled, the theme will:
+
+    - Change text direction to RTL
+    - Mirror layout components
+    - Keep code blocks in LTR direction
+
+    Defaults to ``False``.
+
+    .. versionadded:: 8.2.0
+
 **alabaster**
   `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
   (especially as used in his Requests project), which was itself originally

sphinx/themes/agogo/static/agogo.css.jinja

@@ -2,6 +2,8 @@
  * Sphinx stylesheet -- agogo theme.
  */
 
+@import url("rtl.css");
+
 * {
   margin: 0px;
   padding: 0px;

sphinx/themes/agogo/static/rtl.css.jinja

@@ -0,0 +1,156 @@
+{% if theme_is_rtl|tobool %}
+
+/* Core RTL overrides for Agogo theme */
+body,
+div.header div.rel {
+    direction: rtl !important;
+}
+
+body {
+    text-align: right !important;
+}
+
+/* Header adjustments */
+div.header .headertitle {
+    text-align: right !important;
+    letter-spacing: 0 !important;
+}
+
+p.logo {
+    float: left !important;
+}
+
+/* Content layout */
+div.document {
+    float: right !important;
+}
+
+div.body {
+    {%- if theme_rightsidebar|tobool %}
+    padding-left: 2em !important;
+    padding-right: 0 !important;
+    {%- else %}
+    padding-right: 2em !important;
+    padding-left: 0 !important;
+    {% endif %}
+}
+
+/* Sidebar positioning */
+div.sidebar,
+aside.sidebar {
+    {%- if theme_rightsidebar|tobool %}
+    float: left !important;
+    {%- else %}
+    float: right !important;
+    {% endif %}
+}
+
+/* Lists and margins */
+div.document ul {
+    margin-right: 1.5em !important;
+    margin-left: 0 !important;
+}
+
+div.document dd {
+    margin-right: 1.2em !important;
+    margin-left: 0 !important;
+}
+
+/* Admonitions */
+div.admonition {
+    border-right: 0.2em solid black !important;
+    border-left: none !important;
+}
+
+/* Search elements */
+ul.search {
+    margin: 10px 20px 0 0 !important;
+}
+
+ul.search li {
+    padding: 5px 20px 5px 0 !important;
+    background-position: right 7px !important;
+}
+
+/* Table alignments */
+table.indextable td {
+    text-align: right !important;
+}
+
+/* Footer adjustments */
+div.footer .right {
+    text-align: left !important;
+}
+
+div.footer .left {
+    text-align: right !important;
+}
+
+/* Code blocks - keep LTR */
+div.highlight pre {
+    direction: ltr !important;
+    text-align: left !important;
+}
+
+/* Header links */
+a.headerlink {
+    padding-right: .3em !important;
+    padding-left: 0 !important;
+}
+
+/* Sidebar list adjustments */
+div.sidebar li.toctree-l1 a,
+aside.sidebar li.toctree-l1 a {
+    padding-right: 3px !important;
+    padding-left: 0 !important;
+}
+
+div.sidebar li.toctree-l2 a,
+aside.sidebar li.toctree-l2 a {
+    margin-right: 1em !important;
+    margin-left: 0 !important;
+}
+
+div.sidebar li.toctree-l3 a,
+aside.sidebar li.toctree-l3 a {
+    margin-right: 2em !important;
+    margin-left: 0 !important;
+}
+
+/* Float adjustments */
+.left {
+    float: right !important;
+}
+
+.right {
+    float: left !important;
+}
+
+/* Image alignments */
+img.align-left,
+.figure.align-left,
+object.align-left {
+    float: right !important;
+    margin-left: 1em !important;
+    margin-right: 0 !important;
+}
+
+img.align-right,
+.figure.align-right,
+object.align-right {
+    float: left !important;
+    margin-right: 1em !important;
+    margin-left: 0 !important;
+}
+
+/* Viewcode extension */
+.viewcode-link,
+.viewcode-back {
+    float: left !important;
+}
+
+/* Equation numbers */
+span.eqno {
+    float: left !important;
+}
+{% endif %}

sphinx/themes/basic/static/basic.css.jinja

@@ -4,6 +4,8 @@
 
 /* -- main layout ----------------------------------------------------------- */
 
+@import url("rtl.css");
+
 div.clearer {
     clear: both;
 }

sphinx/themes/basic/static/documentation_options.js.jinja

@@ -10,4 +10,5 @@ const DOCUMENTATION_OPTIONS = {
     NAVIGATION_WITH_KEYS: {{ 'true' if theme_navigation_with_keys|tobool else 'false'}},
     SHOW_SEARCH_SUMMARY: {{ 'true' if show_search_summary else 'false' }},
     ENABLE_SEARCH_SHORTCUTS: {{ 'true' if theme_enable_search_shortcuts|tobool else 'false'}},
+    IS_RTL: {{ 'true' if is_rtl else 'false' }},
 };

sphinx/themes/basic/static/rtl.css.jinja

@@ -0,0 +1,118 @@
+{% if theme_is_rtl|tobool %}
+
+/* Core RTL layout */
+body,
+div.document,
+div.documentwrapper,
+div.body p,
+div.body dd,
+div.body li,
+div.body blockquote {
+    direction: rtl !important;
+}
+
+/* Text alignments */
+body,
+div.body p,
+div.body dd,
+div.body li,
+div.body blockquote,
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6,
+th,
+table.docutils td {
+    text-align: right !important;
+}
+
+/* Layout adjustments */
+div.sphinxsidebar {
+    float: right !important;
+    margin-right: -100% !important;
+}
+
+div.bodywrapper {
+    margin: 0 {{ theme_sidebarwidth|todim }} 0 0 !important;
+}
+
+/* Headers padding */
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    padding: 3px 10px 3px 0 !important;
+}
+
+/* Lists */
+ul,
+ol {
+    padding-right: 30px !important;
+    padding-left: 0 !important;
+}
+
+/* Left-aligned elements */
+div.related li.right,
+#sidebarbutton {
+    float: left !important;
+}
+
+div.related li.right {
+    margin-left: 10px !important;
+    margin-right: 0 !important;
+}
+
+/* Form and search elements */
+div.sphinxsidebar input,
+div.sphinxsidebar #searchbox input[type="text"],
+div.sphinxsidebar #searchbox input[type="submit"] {
+    float: right !important;
+    text-align: right !important;
+}
+
+/* Footnotes */
+.footnote-reference {
+    float: right !important;
+}
+
+.footnote {
+    direction: rtl !important;
+    text-align: right !important;
+}
+
+/* Code blocks - keep LTR */
+pre {
+    direction: ltr !important;
+    text-align: left !important;
+    border-right: 4px solid #ac9 !important;
+    border-left: none !important;
+}
+
+/* Admonitions */
+div.admonition {
+    padding: 7px 10px 7px 7px !important;
+}
+
+/* References and links */
+a.reference.internal,
+a.reference.external {
+    unicode-bidi: bidi-override !important;
+}
+
+/* Sidebar collapsible button */
+{% if theme_collapsiblesidebar|tobool %}
+#sidebarbutton {
+    border-right: 1px solid {{ theme_relbarbgcolor }} !important;
+    border-left: none !important;
+}
+{% endif %}
+
+/* Topic boxes and sidebars */
+div.topic {
+    margin: 0 0 0.5em 1em !important;
+}
+{% endif %}

sphinx/themes/basic/theme.toml

@@ -21,3 +21,4 @@ enable_search_shortcuts = "True"
 globaltoc_collapse = "true"
 globaltoc_includehidden = "false"
 globaltoc_maxdepth = ""
+is_rtl = "false"

sphinx/themes/epub/static/epub.css.jinja

@@ -2,6 +2,8 @@
  * Sphinx stylesheet -- epub theme.
  */
 
+@import url("rtl.css");
+
 /* -- main layout ----------------------------------------------------------- */
 
 {% if theme_writing_mode is defined %}