Merge pull request #793 from readthedocs/agj/update-translations-rebase

Finalized addition of theme localization

Author: agjohnson

.gitignore

@@ -9,10 +9,17 @@
 *.map
 .ropeproject/
 .ruby-version
+bin/
 dist/
 bower_components/
+include/
+lib/
+local/
 node_modules
 npm-debug.log
 package-lock.json
+pip-selfcheck.json
 sphinx_rtd_theme/static/fonts/Lato/
 sphinx_rtd_theme/static/fonts/RobotoSlab/
+.python-version
+.node-version

.readthedocs.yml

@@ -1,5 +1,5 @@
-build:
-  image: latest
+version: 2
 python:
   version: 3.6
-requirements_file: docs/requirements.txt
+  install:
+    - requirements: docs/requirements.txt

.travis.yml

@@ -10,6 +10,7 @@ matrix:
       env: TOXENV=docs
 install:
   - pip install tox-travis
+  - pip install sphinx
 script:
   - tox
 

.tx/config

@@ -0,0 +1,8 @@
+[sphinx-rtd-theme.sphinx-rtd-theme]
+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
+
+[main]
+host = https://www.transifex.com
+type = PO

MANIFEST.in

@@ -1,4 +1,5 @@
 include *.txt
+include babel.cfg
 include LICENSE
 recursive-include sphinx_rtd_theme *.conf
 recursive-include sphinx_rtd_theme *.css
@@ -9,5 +10,7 @@ recursive-include sphinx_rtd_theme *.svg
 recursive-include sphinx_rtd_theme *.ttf
 recursive-include sphinx_rtd_theme *.woff
 recursive-include sphinx_rtd_theme *.woff2
+recursive-include sphinx_rtd_theme/locale *.pot *.po *.mo
 recursive-include tests *.py
 recursive-include tests *.rst
+prune build

README.rst

@@ -1,13 +1,12 @@
-
 **************************
 Read the Docs Sphinx Theme
 **************************
 
 .. image:: https://img.shields.io/pypi/v/sphinx_rtd_theme.svg
    :target: https://pypi.python.org/pypi/sphinx_rtd_theme
-   :alt: Pypi Version 
-.. image:: https://travis-ci.org/rtfd/sphinx_rtd_theme.svg?branch=master
-   :target: https://travis-ci.org/rtfd/sphinx_rtd_theme
+   :alt: Pypi Version
+.. image:: https://travis-ci.org/readthedocs/sphinx_rtd_theme.svg?branch=master
+   :target: https://travis-ci.org/readthedocs/sphinx_rtd_theme
    :alt: Build Status
 .. image:: https://img.shields.io/pypi/l/sphinx_rtd_theme.svg
    :target: https://pypi.python.org/pypi/sphinx_rtd_theme/
@@ -16,39 +15,56 @@ Read the Docs Sphinx Theme
   :target: http://sphinx-rtd-theme.readthedocs.io/en/latest/?badge=latest
   :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: http://www.sphinx-doc.org
-.. _readthedocs.org: http://www.readthedocs.org
-.. _demo: https://sphinx-rtd-theme.readthedocs.io/en/latest/
+.. _Sphinx: http://www.sphinx-doc.org
+.. _Read the Docs: http://www.readthedocs.org
+.. _theme documentation: https://sphinx-rtd-theme.readthedocs.io/en/latest/
 
+Installation
+============
 
-Installing
-==========
+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:: console
 
    pip install sphinx-rtd-theme
 
-For more information read the full installing docs
-`here <https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html>`__.
+To use the theme in your Sphinx project, you will need to add the following to
+your ``conf.py`` file:
 
-.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
+.. code:: python
+
+    import sphinx_rtd_theme
+
+    extensions = [
+        ...
+        "sphinx_rtd_theme",
+    ]
 
+    html_theme = "sphinx_rtd_theme"
+
+For more information read the full documentation on `installing the theme`_
+
+.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
+.. _installing the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html
 
 Configuration
 =============
 
-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 <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__.
+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: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html
 
 Contributing
 ============
 
-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 <https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html>`__.
+If you would like to help modify or translate the theme, you'll find more
+information on contributing in our `contributing guide`_.
+
+.. _contributing guide: https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html

babel.cfg

@@ -0,0 +1,10 @@
+# How setup this file
+# http://babel.pocoo.org/en/latest/setup.html
+# this file description:
+# http://babel.pocoo.org/en/latest/messages.html#extraction-method-mapping-and-configuration
+
+# Extraction from Jinja2 HTML templates
+[jinja2: **/**.html]
+encoding = utf-8
+ignore_tags = script,style
+include_attrs = alt title summary placeholder

docs/changelog.rst

@@ -17,6 +17,8 @@ Other Changes
 --------------
 
 * Add the ``navigation`` template block around the navigation area.
+* Added Spanish translation
+* Added i18n support using Babel
 
 0.4.3
 ======
@@ -93,7 +95,7 @@ Fixes
 * Color accessibility improvements on the left navigation
 
 Other Changes
---------------
+---------------
 
 * Write theme version and build date at top of JavaScript and CSS
 * Changed code and literals to use a native font stack (#612)

docs/conf.py

@@ -4,11 +4,11 @@
 import os
 import re
 
-sys.path.append(os.path.abspath('..'))
+if not 'READTHEDOCS' in os.environ:
+    sys.path.insert(0, os.path.abspath('..'))
 sys.path.append(os.path.abspath('./demo/'))
 
 from sphinx.locale import _
-
 from sphinx_rtd_theme import __version__
 
 
@@ -26,11 +26,14 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinxcontrib.httpdomain',
+    'sphinx_rtd_theme',
 ]
 
 templates_path = ['_templates']
 source_suffix = '.rst'
 exclude_patterns = []
+locale_dirs = ['locale/']
+gettext_compact = False
 
 master_doc = 'index'
 suppress_warnings = ['image.nonlocal_uri']

docs/contributing.rst

@@ -1,89 +1,113 @@
+************
+Contributing
+************
 
-***********************************
-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
+   .. code:: console
 
-       pip install sphinx sphinxcontrib-httpdomain
+       pip install -e '.[dev]'
 
-#. Install sass.
+#. Install SASS.
 
-   .. code:: bash
+   .. code:: console
 
        gem install sass
 
-#. Install node, bower, grunt, and theme dependencies.
-
-   .. code:: bash
-
-       # Install node
-       brew install node
+#. Install Bower, Grunt, and theme dependencies locally.
 
-       # Install bower and grunt
-       npm install -g bower grunt-cli
+   .. code:: console
 
-       # 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
+--------------
 
-.. code::
+Changes to the theme can be compiled and tested with the default Grunt task:
+
+.. code:: console
 
     grunt
 
-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:: console
+
+    grunt build
+
+.. _Bower: http://www.bower.io
+.. _SASS: http://www.sass-lang.com
+.. _Wyrm: http://www.github.com/snide/wyrm/
+.. _Grunt: http://www.gruntjs.com
+.. _Sphinx: http://www.sphinx-doc.org/en/stable/
+
+Translations
+============
+
+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
+:doc:`rtd:development/i18n`
+
+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:: console
 
-#. 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.
+    python setup.py update_translations
 
-.. _bower: http://www.bower.io
-.. _sass: http://www.sass-lang.com
-.. _wyrm: http://www.github.com/snide/wyrm/
-.. _grunt: http://www.gruntjs.com
-.. _node: http://www.nodejs.com
-.. _sphinx: http://www.sphinx-doc.org/en/stable/
+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: https://www.transifex.com/readthedocs/sphinx-rtd-theme
 
-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/__init__.py``, ``bower.json`` and ``package.json`` --
    we try to follow `semver <http://semver.org/>`_, 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 ``python setup.py update_translations`` 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
+    .. code:: console
 
-        $ rm -rf dist/
-        $ python setup.py sdist bdist_wheel
-        $ twine upload --sign --identity [email protected] dist/*
+        rm -rf dist/
+        python setup.py sdist bdist_wheel
+        twine upload --sign --identity [email protected] dist/*