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

.gitignore

@@ -1,7 +1,6 @@
 *.pyc
 *.egg-info
 *.egg
-*.mo
 *build/
 .tox
 .coverage

.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

Gruntfile.js

@@ -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 setup.py extract_messages'
+      },
+      babel_compile: {
+        cmd: 'python setup.py compile_catalog'
+      },
+      tx_pull: {
+        cmd: 'tx pull'
+      },
+      tx_push: {
+        cmd: 'tx push --source'
       }
     },
     clean: {
@@ -184,6 +199,33 @@ module.exports = function(grunt) {
   grunt.loadNpmTasks('grunt-open');
   grunt.loadNpmTasks('grunt-browserify');
 
-  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', [
+      '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('i18n', [
+      'exec:babel_extract',
+      'exec:tx_push',
+      'exec:tx_pull',
+      'exec:babel_compile',
+      'exec:build_sphinx:es'
+  ]);
 }

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
+.. 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,45 +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:: bash
 
    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>`__.
-
-Translations
-------------
+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: https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html

docs/changelog.rst

@@ -2,23 +2,21 @@
 Changelog
 *********
 
-Master
+master
 ======
 
 New Features
 -------------
 
-* Added Spanish translation
-* Added i18n support using Babel
-* Added Translation Guide documentation
-
 Fixes
 -----
 
 Other Changes
 --------------
 
 * Add the ``navigation`` template block around the navigation area.
+* Added Spanish translation
+* Added i18n support using Babel
 
 0.4.3
 ======

docs/conf.py

@@ -4,11 +4,10 @@
 import os
 import re
 
-sys.path.append(os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('..'))
 sys.path.append(os.path.abspath('./demo/'))
 
 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']

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
 
-       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::
 
     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:: bash
+
+    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:: 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: 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 ``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 setup.py sdist bdist_wheel
-        $ twine upload --sign --identity security@readthedocs.org dist/*
+        rm -rf dist/
+        python setup.py sdist bdist_wheel
+        twine upload --sign --identity security@readthedocs.org dist/*