Skip to content

Commit caa3373

Browse files
agjohnsonagjohnson
committed
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
1 parent f9a2fe4 commit caa3373

File tree

20 files changed

+539
-348
lines changed

20 files changed

+539
-348
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
*.pyc
22
*.egg-info
33
*.egg
4-
*.mo
54
*build/
65
.tox
76
.coverage

‎.tx/config‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[sphinx-rtd-theme.sphinx-rtd-theme]
2+
file_filter = sphinx_rtd_theme/locale/<lang>/LC_MESSAGES/sphinx.po
3+
source_file = sphinx_rtd_theme/locale/en/LC_MESSAGES/sphinx.po
4+
source_lang = en
5+
6+
[main]
7+
host = https://www.transifex.com
8+
type = PO

‎Gruntfile.js‎

Lines changed: 45 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,22 @@ module.exports = function(grunt) {
140140
cmd: 'bower update'
141141
},
142142
build_sphinx: {
143-
cmd: 'sphinx-build docs/ docs/build'
143+
cmd: function (locale) {
144+
locale = (typeof locale !== 'undefined') ? locale : 'en';
145+
return 'sphinx-build -D language=' + locale + ' docs/ docs/build/html'
146+
}
147+
},
148+
babel_extract: {
149+
cmd: 'python setup.py extract_messages'
150+
},
151+
babel_compile: {
152+
cmd: 'python setup.py compile_catalog'
153+
},
154+
tx_pull: {
155+
cmd: 'tx pull'
156+
},
157+
tx_push: {
158+
cmd: 'tx push --source'
144159
}
145160
},
146161
clean: {
@@ -184,6 +199,33 @@ module.exports = function(grunt) {
184199
grunt.loadNpmTasks('grunt-open');
185200
grunt.loadNpmTasks('grunt-browserify');
186201

187-
grunt.registerTask('default', ['exec:bower_update','clean','copy:fonts','sass:dev','browserify:dev','usebanner','exec:build_sphinx','connect','open','watch']);
188-
grunt.registerTask('build', ['exec:bower_update','clean','copy:fonts','sass:build','browserify:build','uglify','usebanner','exec:build_sphinx']);
202+
grunt.registerTask('default', [
203+
'exec:bower_update',
204+
'clean',
205+
'copy:fonts',
206+
'sass:dev',
207+
'browserify:dev',
208+
'usebanner',
209+
'exec:build_sphinx',
210+
'connect',
211+
'open',
212+
'watch'
213+
]);
214+
grunt.registerTask('build', [
215+
'exec:bower_update',
216+
'clean',
217+
'copy:fonts',
218+
'sass:build',
219+
'browserify:build',
220+
'uglify',
221+
'usebanner',
222+
'exec:build_sphinx'
223+
]);
224+
grunt.registerTask('i18n', [
225+
'exec:babel_extract',
226+
'exec:tx_push',
227+
'exec:tx_pull',
228+
'exec:babel_compile',
229+
'exec:build_sphinx:es'
230+
]);
189231
}

‎README.rst‎

Lines changed: 36 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
1-
21
**************************
32
Read the Docs Sphinx Theme
43
**************************
54

65
.. image:: https://img.shields.io/pypi/v/sphinx_rtd_theme.svg
76
:target: https://pypi.python.org/pypi/sphinx_rtd_theme
87
:alt: Pypi Version
9-
.. image:: https://travis-ci.org/rtfd/sphinx_rtd_theme.svg?branch=master
10-
:target: https://travis-ci.org/rtfd/sphinx_rtd_theme
8+
.. image:: https://travis-ci.org/readthedocs/sphinx_rtd_theme.svg?branch=master
9+
:target: https://travis-ci.org/readthedocs/sphinx_rtd_theme
1110
:alt: Build Status
1211
.. image:: https://img.shields.io/pypi/l/sphinx_rtd_theme.svg
1312
:target: https://pypi.python.org/pypi/sphinx_rtd_theme/
@@ -16,45 +15,56 @@ Read the Docs Sphinx Theme
1615
:target: http://sphinx-rtd-theme.readthedocs.io/en/latest/?badge=latest
1716
:alt: Documentation Status
1817

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

23-
.. _sphinx: http://www.sphinx-doc.org
24-
.. _readthedocs.org: http://www.readthedocs.org
25-
.. _demo: https://sphinx-rtd-theme.readthedocs.io/en/latest/
23+
.. _Sphinx: http://www.sphinx-doc.org
24+
.. _Read the Docs: http://www.readthedocs.org
25+
.. _theme documentation: https://sphinx-rtd-theme.readthedocs.io/en/latest/
2626

27+
Installation
28+
============
2729

28-
Installing
29-
==========
30+
This theme is distributed on PyPI_ and can be installed with ``pip``:
3031

31-
The theme is distributed on PyPI_ and can be installed with pip::
32+
.. code:: bash
3233
3334
pip install sphinx_rtd_theme
3435
35-
For more information read the full installing docs
36-
`here <https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html>`__.
36+
To use the theme in your Sphinx project, you will need to add the following to
37+
your ``conf.py`` file:
3738

38-
.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
39+
.. code:: python
40+
41+
import sphinx_rtd_theme
42+
43+
extensions = [
44+
...
45+
"sphinx_rtd_theme",
46+
]
3947
48+
html_theme = "sphinx_rtd_theme"
49+
50+
For more information read the full documentation on `installing the theme`_
51+
52+
.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
53+
.. _installing the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html
4054

4155
Configuration
4256
=============
4357

44-
The ``sphinx_rtd_theme`` is highly customizable on both the page level and on a global level.
45-
To see all the possible configuration options read the configuring docs
46-
`here <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__.
58+
This theme is highly customizable on both the page level and on a global level.
59+
To see all the possible configuration options, read the documentation on
60+
`configuring the theme`_.
4761

62+
.. _configuring the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html
4863

4964
Contributing
5065
============
5166

52-
If you would like to help improve the theme or have more control
53-
over the theme in case of a fork please read our contributing guide
54-
`here <https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html>`__.
55-
56-
Translations
57-
------------
67+
If you would like to help modify or translate the theme, you'll find more
68+
information on contributing in our `contributing guide`_.
5869

59-
You can help to translate the Read the Docs Sphinx Theme,
60-
please read the :doc:`translations </docs/translations>` guide for more details.
70+
.. _contributing guide: https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html

‎docs/changelog.rst‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,21 @@
22
Changelog
33
*********
44

5-
Master
5+
master
66
======
77

88
New Features
99
-------------
1010

11-
* Added Spanish translation
12-
* Added i18n support using Babel
13-
* Added Translation Guide documentation
14-
1511
Fixes
1612
-----
1713

1814
Other Changes
1915
--------------
2016

2117
* Add the ``navigation`` template block around the navigation area.
18+
* Added Spanish translation
19+
* Added i18n support using Babel
2220

2321
0.4.3
2422
======

‎docs/conf.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,10 @@
44
import os
55
import re
66

7-
sys.path.append(os.path.abspath('..'))
7+
sys.path.insert(0, os.path.abspath('..'))
88
sys.path.append(os.path.abspath('./demo/'))
99

1010
from sphinx.locale import _
11-
1211
from sphinx_rtd_theme import __version__
1312

1413

@@ -32,6 +31,8 @@
3231
templates_path = ['_templates']
3332
source_suffix = '.rst'
3433
exclude_patterns = []
34+
locale_dirs = ['locale/']
35+
gettext_compact = False
3536

3637
master_doc = 'index'
3738
suppress_warnings = ['image.nonlocal_uri']

‎docs/contributing.rst‎

Lines changed: 70 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,113 @@
1+
************
2+
Contributing
3+
************
14

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

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

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

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

1921
Set up your environment
20-
=======================
22+
-----------------------
2123

22-
#. Install sphinx_ into a virtual environment.
24+
#. Install Sphinx_ and documentation build dependencies.
2325

2426
.. code:: bash
2527
26-
pip install sphinx sphinxcontrib-httpdomain
28+
pip install -r docs/requirements.txt
2729
28-
#. Install sass.
30+
#. Install SASS.
2931

3032
.. code:: bash
3133
3234
gem install sass
3335
34-
#. Install node, bower, grunt, and theme dependencies.
36+
#. Install Bower, Grunt, and theme dependencies locally.
3537

3638
.. code:: bash
3739
38-
# Install node
39-
brew install node
40-
41-
# Install bower and grunt
42-
npm install -g bower grunt-cli
43-
44-
# Now that everything is installed, let's install the theme dependencies.
4540
npm install
4641
47-
Now that our environment is set up, make sure you're in your virtual environment, go to
48-
this repository in your terminal and run grunt:
42+
Making changes
43+
--------------
44+
45+
Changes to the theme can be compiled and tested with the default Grunt task:
4946

5047
.. code::
5148
5249
grunt
5350
54-
This default task will do the following **very cool things that make it worth the trouble**:
51+
This default task will do the following:
52+
53+
#. Install and update any Bower dependencies.
54+
#. Build the static CSS from SASS source files.
55+
#. Build the demo documentation.
56+
#. Watch for changes to the SASS files and documentation and rebuild everything
57+
on any detected changes.
58+
59+
Alternatively, if you don't need to watch the files, Grunt can be called with
60+
the same task used for releases:
61+
62+
.. code:: bash
63+
64+
grunt build
65+
66+
.. _Bower: http://www.bower.io
67+
.. _SASS: http://www.sass-lang.com
68+
.. _Wyrm: http://www.github.com/snide/wyrm/
69+
.. _Grunt: http://www.gruntjs.com
70+
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
71+
72+
Translations
73+
============
74+
75+
Translations are managed using `Transifex`_. You can join any of the existing
76+
language teams or request a new language is added to the project. For more
77+
information on our translation standards, see our docs on
78+
:doc:`rtd:development/i18n`
79+
80+
Periodically, core team should update the translation files outside our normal
81+
releases. Someone from the core team, with write access to Transifex, should run
82+
the following:
83+
84+
.. code:: bash
5585
56-
#. Install and update any bower dependencies.
57-
#. Run sphinx and build new docs.
58-
#. Watch for changes to the sass files and build css from the changes.
59-
#. Rebuild the sphinx docs anytime it notices a change to ``.rst``, ``.html``, ``.js``
60-
or ``.css`` files.
86+
grunt i18n
6187
62-
.. _bower: http://www.bower.io
63-
.. _sass: http://www.sass-lang.com
64-
.. _wyrm: http://www.github.com/snide/wyrm/
65-
.. _grunt: http://www.gruntjs.com
66-
.. _node: http://www.nodejs.com
67-
.. _sphinx: http://www.sphinx-doc.org/en/stable/
88+
This will extract new messages, upload the messages to Transifex, and will
89+
update our local translation files. Changes can be checked in to a branch and
90+
put up for review.
6891

92+
.. _Transifex: https://www.transifex.com/readthedocs/sphinx-rtd-theme
6993

70-
Releasing the Theme
94+
Releasing the theme
7195
===================
7296

73-
When you release a new version,
74-
you should do the following:
97+
To release a new version of the theme, core team will take the following steps:
7598

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

85109
.. code:: bash
86110
87-
$ rm -rf dist/
88-
$ python setup.py sdist bdist_wheel
89-
$ twine upload --sign --identity [email protected] dist/*
111+
rm -rf dist/
112+
python setup.py sdist bdist_wheel
113+
twine upload --sign --identity [email protected] dist/*

0 commit comments

Comments
 (0)