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
readthedocs · Jul 17, 2019 · caa3373 · caa3373
1 parent f9a2fe4
commit caa3373
Show file tree

Hide file tree

Showing 20 changed files with 539 additions and 348 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,6 @@
 *.pyc
 *.egg-info
 *.egg
-*.mo
 *build/
 .tox
 .coverage

diff --git a/.tx/config b/.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
diff --git a/Gruntfile.js b/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'
+ ]);
 }
diff --git a/README.rst b/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
diff --git a/docs/changelog.rst b/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
 ======

diff --git a/docs/conf.py b/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']

diff --git a/docs/contributing.rst b/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 [email protected] dist/*
+ rm -rf dist/
+ python setup.py sdist bdist_wheel
+ twine upload --sign --identity [email protected] dist/*