Skip to content
Browse files

Continuation of adding translations to theme

This builds on top of #405, addressing the outstanding review feedback. It:

* Moves workflow to our standard Transifex workflow, drops recommendation for
  running babel commands by hand
* Configures Transifex
* Moves all of the commands needed to maintain translations into Grunt
* Sets up docs for translation testing
* Covers installation in docs better
* Drops recommendation for installation through submodules
* Drops superfluous translation documentation
* Cleans up some of the code
* Updates a lot of related documentation
* Updates files at Transifex and brings in full translations back to the
  translation files in the repository
  • Loading branch information...
agjohnson committed Jul 17, 2019
1 parent f9a2fe4 commit caa33732973ad2b9bf78aa3668f3e4ccb9627ca5
@@ -1,7 +1,6 @@
@@ -0,0 +1,8 @@
file_filter = sphinx_rtd_theme/locale/<lang>/LC_MESSAGES/sphinx.po
source_file = sphinx_rtd_theme/locale/en/LC_MESSAGES/sphinx.po
source_lang = en

host =
type = PO
@@ -140,7 +140,22 @@ module.exports = function(grunt) {
cmd: 'bower update'
build_sphinx: {
cmd: 'sphinx-build docs/ docs/build'
cmd: function (locale) {
locale = (typeof locale !== 'undefined') ? locale : 'en';
return 'sphinx-build -D language=' + locale + ' docs/ docs/build/html'
babel_extract: {
cmd: 'python extract_messages'
babel_compile: {
cmd: 'python compile_catalog'
tx_pull: {
cmd: 'tx pull'
tx_push: {
cmd: 'tx push --source'
clean: {
@@ -184,6 +199,33 @@ module.exports = function(grunt) {

grunt.registerTask('default', ['exec:bower_update','clean','copy:fonts','sass:dev','browserify:dev','usebanner','exec:build_sphinx','connect','open','watch']);
grunt.registerTask('build', ['exec:bower_update','clean','copy:fonts','sass:build','browserify:build','uglify','usebanner','exec:build_sphinx']);
grunt.registerTask('default', [
grunt.registerTask('build', [
grunt.registerTask('i18n', [
@@ -1,13 +1,12 @@

Read the Docs Sphinx Theme

.. image::
:alt: Pypi Version
.. image::
.. image::
:alt: Build Status
.. image::
@@ -16,45 +15,56 @@ Read the Docs Sphinx Theme
:alt: Documentation Status

The ``sphinx_rtd_theme`` is a sphinx_ theme designed to look modern and be mobile-friendly.
This theme is primarily focused to be used on readthedocs.org_ but can work with your
own sphinx projects. To read more and see a working demo_ head over to readthedocs.org_.
This Sphinx_ theme was designed to provide a great reader experience for
documentation users on both desktop and mobile devices. This theme is used
primarily on `Read the Docs`_ but can work with any Sphinx project. You can find
a working demo of the theme in the `theme documentation`_

.. _sphinx:
.. _demo:
.. _Sphinx:
.. _Read the Docs:
.. _theme documentation:


This theme is distributed on PyPI_ and can be installed with ``pip``:

The theme is distributed on PyPI_ and can be installed with pip::
.. code:: bash
pip install sphinx_rtd_theme
For more information read the full installing docs
`here <>`__.
To use the theme in your Sphinx project, you will need to add the following to
your ```` file:

.. _PyPI:
.. code:: python
import sphinx_rtd_theme
extensions = [
html_theme = "sphinx_rtd_theme"
For more information read the full documentation on `installing the theme`_

.. _PyPI:
.. _installing the theme:


The ``sphinx_rtd_theme`` is highly customizable on both the page level and on a global level.
To see all the possible configuration options read the configuring docs
`here <>`__.
This theme is highly customizable on both the page level and on a global level.
To see all the possible configuration options, read the documentation on
`configuring the theme`_.

.. _configuring the theme:


If you would like to help improve the theme or have more control
over the theme in case of a fork please read our contributing guide
`here <>`__.

If you would like to help modify or translate the theme, you'll find more
information on contributing in our `contributing guide`_.

You can help to translate the Read the Docs Sphinx Theme,
please read the :doc:`translations </docs/translations>` guide for more details.
.. _contributing guide:
@@ -2,23 +2,21 @@


New Features

* Added Spanish translation
* Added i18n support using Babel
* Added Translation Guide documentation


Other Changes

* Add the ``navigation`` template block around the navigation area.
* Added Spanish translation
* Added i18n support using Babel

@@ -4,11 +4,10 @@
import os
import re

sys.path.insert(0, os.path.abspath('..'))

from sphinx.locale import _

from sphinx_rtd_theme import __version__

@@ -32,6 +31,8 @@
templates_path = ['_templates']
source_suffix = '.rst'
exclude_patterns = []
locale_dirs = ['locale/']
gettext_compact = False

master_doc = 'index'
suppress_warnings = ['image.nonlocal_uri']
@@ -1,89 +1,113 @@

Contributing or modifying the theme
This project follows the Read the Docs :doc:`code of conduct
<rtd:code-of-conduct>`. If you are not familiar with our code of conduct policy,
take a minute to read the policy before starting with your first contribution.

The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm
using bower_ to manage these dependencies and sass_ to build the css. The good news is
I have a very nice set of grunt_ operations that will not only load these dependencies, but watch
for changes, rebuild the sphinx demo docs and build a distributable version of the theme.
The bad news is this means you'll need to set up your environment similar to that
of a front-end developer (vs. that of a python developer). That means installing node and ruby.

.. seealso::
Modifying the theme

If you are unsure of appropriate actions to take while interacting with our
community please read our :doc:`Code of Conduct <rtd:code-of-conduct>`.
The styles for this theme use SASS_ and a custom CSS framework called Wyrm_. We
use Bower_ to manage these dependencies and SASS_ to build the CSS. Grunt_ is
used to watch for changes, rebuild the static assets, and rebuild the Sphinx
demo documentation.

.. note::
The installation of Ruby and Node is outside the scope of this
documentation. You will need both in order to make changes to this theme.

Set up your environment

#. Install sphinx_ into a virtual environment.
#. Install Sphinx_ and documentation build dependencies.

.. code:: bash
pip install sphinx sphinxcontrib-httpdomain
pip install -r docs/requirements.txt
#. Install sass.
#. Install SASS.

.. code:: bash
gem install sass
#. Install node, bower, grunt, and theme dependencies.
#. Install Bower, Grunt, and theme dependencies locally.

.. code:: bash
# Install node
brew install node
# Install bower and grunt
npm install -g bower grunt-cli
# Now that everything is installed, let's install the theme dependencies.
npm install
Now that our environment is set up, make sure you're in your virtual environment, go to
this repository in your terminal and run grunt:
Making changes

Changes to the theme can be compiled and tested with the default Grunt task:

.. code::


This default task will do the following **very cool things that make it worth the trouble**:
This default task will do the following:

#. Install and update any Bower dependencies.
#. Build the static CSS from SASS source files.
#. Build the demo documentation.
#. Watch for changes to the SASS files and documentation and rebuild everything
on any detected changes.

Alternatively, if you don't need to watch the files, Grunt can be called with
the same task used for releases:

.. code:: bash
grunt build
.. _Bower:
.. _SASS:
.. _Wyrm:
.. _Grunt:
.. _Sphinx:


Translations are managed using `Transifex`_. You can join any of the existing
language teams or request a new language is added to the project. For more
information on our translation standards, see our docs on

Periodically, core team should update the translation files outside our normal
releases. Someone from the core team, with write access to Transifex, should run
the following:

.. code:: bash
#. Install and update any bower dependencies.
#. Run sphinx and build new docs.
#. Watch for changes to the sass files and build css from the changes.
#. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js``
or ``.css`` files.
grunt i18n
.. _bower:
.. _sass:
.. _wyrm:
.. _grunt:
.. _node:
.. _sphinx:
This will extract new messages, upload the messages to Transifex, and will
update our local translation files. Changes can be checked in to a branch and
put up for review.

.. _Transifex:

Releasing the Theme
Releasing the theme

When you release a new version,
you should do the following:
To release a new version of the theme, core team will take the following steps:

#. Bump the version in ``sphinx_rtd_theme/``, ``bower.json`` and ``package.json`` --
we try to follow `semver <>`_, so be careful with breaking changes.
#. Update the changelog (``docs/changelog.rst``) with the version information.
#. Run a ``grunt build`` to rebuild all the theme assets.
#. Run ``grunt build`` to rebuild all the theme assets.
#. Run ``grunt i18n`` to compile new translation files and update Transifex
#. Commit that change.
#. Tag the release in git: ``git tag $NEW_VERSION``.
#. Push the tag to GitHub: ``git push --tags origin``.
#. Upload the package to PyPI:

.. code:: bash
$ rm -rf dist/
$ python sdist bdist_wheel
$ twine upload --sign --identity dist/*
rm -rf dist/
python sdist bdist_wheel
twine upload --sign --identity dist/*

0 comments on commit caa3373

Please sign in to comment.
You can’t perform that action at this time.