Support for right-to-left (rtl) languages

[julienmalard]

I arranged the RTD stylesheet to allow support for rtl (right-to-left) languages.

A few points:

• Text direction is determined by the page content, not the language declared. Therefore, only pages that are actually written in (or have at least the first heading translated to) a rtlscript will appear as rtl.
• The entire page is mirrored, including navigation, etc.
• This works pretty much impeccably well on Firefox including with responsive design, which supports rtl detection.
• For browsers that do not have support for rtl detection (:dir(rtl) attribute) yet, it works passably well (a few odd paragraph alignments and borders, and the navigation is still on the left side). But at least rtl text is readable, even on these browsers (the current RTD theme displays RTL text in the wrong order). And it is expected that other browsers will add rtl detection support soon, so this should be a temporary problem.

In summary, this pull request:

• Appears to work perfectly for Firefox.
• Works better than the current theme on other browsers.
• Has no impact on left-to-right pages, no matter what browser is used.

For an example, see our partially translated Urdu site in which I overrode the default RTD theme with this one:
http://tinamit.readthedocs.io/ur/latest/docu/Conectado.html

Fixes #498

[ericholscher]

Thanks for the contribution. However, these changes have been made to our CSS files, not our actual base SASS templates. They should be made there to be integrated into the theme properly:

https://github.com/rtfd/sphinx_rtd_theme/tree/master/sass

More docs on how to contribute and build things are here: https://github.com/rtfd/sphinx_rtd_theme#contributing-or-modifying-the-theme

[julienmalard]

Ah, thank you! I will try to learn SASS and get back to you then.

[Blendify]

To me, it appears that the css file changes are not needed at all. Also, I would rather set this up as a theme option that should default to auto or ltr

[Blendify]

See my above comment

[julienmalard]

Yes, I will try to get around to it soon!

…

________________________________ દ્વારા: Aaron Carlisle <[email protected]> મોકલ્યું: 16 ડિસેમ્બર 2017 00:10:59 પ્રતિ: rtfd/sphinx_rtd_theme Cc: Julien Malard; Author વિષય: Re: [rtfd/sphinx_rtd_theme] Support for right-to-left (rtl) languages (#498) @Blendify requested changes on this pull request. See my above comment — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#498 (review)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AKMb62xx58VLKbvmVwNKBeU4CGa7Rc4Rks5tA1DigaJpZM4Q_XtQ>.

[Blendify]

Please revert changes to sphinx_rtd_theme/static/css/theme.css

[Blendify]

NM I just did.

[julienmalard]

Thank you! I am trying to incorporate all of the css changes I had made into the original sass files (will update once I think I have finished).

[strophy]

Just checking in on progress with this issue - I am also using RTL languages and have hacked together some CSS conditional on the language being used, but would much prefer to have this done at the SASS level, since my overrides break some of the layout. Is there a more elegant way to do this until 0.5 milestone is reached?

If anyone is interested in the CSS, see this site: https://docs.dash.org/ar/latest/

[julienmalard]

Hi,
Thanks for checking up! I really should get back to this...

I have learned SASS since my last comment and was recently searching for an automated gulp extension to add conditional RTL rules, but can't seem to find any. So I think I wil have to try to do this at the SASS level, property-by-property.

I will try to get to this next week, and would be very happy to collaborate. My code for now detects the first word of a page and decides whether it is RTL or LTR language (so that it automatically sets the direction as translations are added and made).

شكرا
-ژولئیں

[strophy]

I'm not familiar with SASS so won't be much help unfortunately.... RTD sets the language correctly in the HTML tag though, so maybe you could try and detect direction based on that instead? My link above also modifies the CSS to move the navigation to the right of the page, but some more work is needed there to get this functioning properly on small screens.

[julienmalard]

Hello,

Thanks! The problem I ran into with language tags is that there are a ton of languages that use different writing systems, and I did not fancy having to make a list of all possible languages that use each of the RTL scripts (arabic, divehi, hebrew, nko and probably a few others I have overlooked!), especially since there are quite a few languages that use arabic variants...

Out of interest, what differences are there between your implementation and mine (https://tinamit.readthedocs.io/ur/latest/docu/Modelo.html), navigation bar aside? I will try to keep the best of both for the final SASS version.

Will keep you posted,
Julien

[strophy]

I think yours focuses more on text styles, while the main thing I tried to do was play with the navigation. I also integrated the CSS in a different way from conf.py, and use a different style of language selector. I might try and get the toc-expand toggles properly aligned and fix the breadcrumbs and GitHub link over the next few days, keep an eye on this file to see if anything useful is in there for you: https://github.com/dashpay/docs/blob/master/_static/style.css

[strophy]

I've made more changes to the CSS overrides on my site and quite happy with the way it is looking now. Most changes are to get the navigation tree working correctly, and I integrated changes from #291 as well to fix indentation of lists. I'm not able to convert this to SASS, but hope this is useful to someone.

CSS: https://github.com/dashpay/docs/blob/master/_static/style.css
Result: https://docs.dash.org/ar/latest/

[strophy]

I've added conditional CSS to support Arabic on small screens (mobile) as well. A language switcher was also added, although this does not exist in the parent theme, so that CSS would need to be removed if this was to be integrated into the Sphinx RTD theme one day.

CSS: https://github.com/dashpay/docs/blob/master/_static/style.css
Result: https://docs.dash.org/ar/latest/

[julienmalard]

Interesting! I love the language switcher; much easier to find than on the original RTD theme.

[julienmalard]

Hello,

I got it to work with SASS! At least mostly. If anyone could get the little arrows on the next and previous buttons to work it would be appreciated. :)

Please let me know if this looks better now.
Regards,
Julien Malard

[julienmalard]

Hello,
Any news?
-Julien Malard

[julienmalard]

Hello,
Any news? Please let me know if I can contribute anything.

[Blendify]

This is updated in #986 please follow the discussion there instead