IntenseWebs/sphinx_rtd_theme
3
0
Fork 0
mirror of https://github.com/readthedocs/sphinx_rtd_theme.git synced 2025-02-25 18:55:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

Continuation of adding translations to theme

Browse Source 
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
This commit is contained in:
Anthony Johnson
2019-07-16 20:27:16 -06:00
parent f9a2fe45d3
commit caa3373297
20 changed files with 540 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/changelog.rst
View File

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

5
docs/conf.py
View File

@@ -4,11 +4,10 @@ import sys
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 @@ extensions = [
templates_path = ['_templates']
source_suffix = '.rst'
exclude_patterns = []
locale_dirs = ['locale/']
gettext_compact = False
master_doc = 'index'
suppress_warnings = ['image.nonlocal_uri']

116
docs/contributing.rst
View File

@@ -1,82 +1,106 @@
************
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.
Modifying the theme
===================
.. seealso::
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.
#. 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.
#. 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.
.. _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/
Alternatively, if you don't need to watch the files, Grunt can be called with
the same task used for releases:
.. code:: bash
Releasing the Theme
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
grunt i18n
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
===================
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``.
@@ -84,6 +108,6 @@ you should do the following:
.. 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/*

9
docs/index.rst
View File

@@ -6,15 +6,18 @@
installing
configuring
changelog
contributing
translations
.. toctree::
:maxdepth: 1
:hidden:
changelog
.. toctree::
:maxdepth: 2
:numbered:
:caption: Demo Documents
:caption: Demo Documentation
demo/structure
demo/demo

27
docs/installing.rst
View File

@@ -1,11 +1,7 @@
************
Installation
************
Via Python Package
==================
Install the package (or add it to your ``requirements.txt`` file):
.. code:: bash
@@ -16,17 +12,18 @@ In your ``conf.py`` file:
.. code:: python
html_theme = "sphinx_rtd_theme"
import sphinx_rtd_theme
Via Git or Download
===================
Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
``conf.py`` file:
.. code:: python
extensions = [
...
'sphinx_rtd_theme',
]
html_theme = "sphinx_rtd_theme"
html_theme_path = ["_themes", ]
.. note::
Adding this theme as an extension is what enables localization of theme
strings in your translated output. If these strings are not translated in
your output, either we lack the localized strings for your locale, or you
are using an old version of the theme.

192
docs/translations.rst
View File

@@ -1,192 +0,0 @@
******************
Translation Guide
******************
.. contents::
You can help to translate the Read the Docs Sphinx Theme.
Installation
============
For translating the Read the Docs Sphinx Theme you will need to install the following packages:
.. code:: bash
$ pip install babel Jinja2
Translating Applications with Babel
-----------------------------------
After you marked all the strings you want to translate in this Sphinx theme with the gettext function
alias ``_('str')`` or ``{% trans %}string 1, string 2, string 3, etc.{% endtrans %}`` blocks.
Then it’s time to create a .pot file. A .pot file contains all the strings and is the template for a
.po file which contains the translated strings. The ``babel`` package can do all that for you.
Configuration
=============
For enable the *Internationalization and Localization* for this Sphinx Theme, you will need checkout
the following configurations:
Translations files
------------------
The translations files are based on ``gettext`` format and they are placed at the
:file:`sphinx_rtd_theme/locale/` directory, like it showing the following structure:
.. code:: bash
sphinx_rtd_theme/locale/
├── es
│   └── LC_MESSAGES
│   ├── sphinx.mo
│   └── sphinx.po
└── sphinx.pot
:file:`sphinx_rtd_theme/locale/<LANG>/LC_MESSAGES/`
This folder contains a specific language is the **Gettext format**.
:file:`sphinx.pot`
This file is the **Portable Object Template** Gettext format.
:file:`sphinx.po`
This file is the **Portable Object** Gettext format to translate.
Babel Configurations
--------------------
The ``babel`` packages provides commands for integration into :file:`setup.py` scripts, based on either
the ``distutils`` package that is part of the Python standard library, or the third-party ``setuptools``
package.
Then :file:`setup.cfg` file simply configures the behavior of the various setup commands for this package.
This file contains the options that you can be specified on the command-line. The :file:`setup.cfg` file
at root folder of this Sphinx theme, look like the following:
.. code:: cfg
[bdist_wheel]
universal = 1
# Babel configurations for setup.py scripts
[compile_catalog]
domain = sphinx
directory = sphinx_rtd_theme/locale/
[extract_messages]
mapping_file = babel.cfg
output_file = sphinx_rtd_theme/locale/sphinx.pot
keywords = _ l_ lazy_gettext
[init_catalog]
input_file = sphinx_rtd_theme/locale/sphinx.pot
output_file = sphinx_rtd_theme/locale/$LANG/LC_MESSAGES/sphinx.po
[update_catalog]
domain = sphinx
input_file = sphinx_rtd_theme/locale/sphinx.pot
output_dir = sphinx_rtd_theme/locale/
If the command has been correctly installed or registered, a project's setup.py script should
allow you to use the following command:
.. code:: bash
$ python ./setup.py subcommand options
Execute the follow command for more options and follow these instructions to get details:
.. code:: bash
$ python ./setup.py --help-commands
Extraction Configurations
-------------------------
First of all you have to get into the folder where you have your Sphinx theme and create a mapping file
called :file:`babel.cfg` that contains the **extraction from Jinja2 HTML templates** configurations.
For typical Sphinx extensions, this is what you want in there:
.. code:: cfg
# Extraction from Jinja2 HTML templates
[jinja2: **/**.html]
encoding = utf-8
ignore_tags = script,style
include_attrs = alt title summary placeholder
.. seealso::
More details check out the following links:
- `How setup this file <http://babel.pocoo.org/en/latest/setup.html>`_
- `A previous file example description <http://babel.pocoo.org/en/latest/messages.html#extraction-method-mapping-and-configuration>`_
Administrative Tasks
====================
The ``babel`` package have a *Distutils/Setuptools Integration* which supports the options
defined in the :file:`setup.cfg` file that can be executed via command line.
These options are the commonly using as **"Translations Administrative Tasks"** and the most
used tasks are described below:
Extract messages
----------------
It can extract localizable messages from a variety of difference source files,
and generate a PO (portable object) template file from the collected messages.
Running the following command will produce a PO template file:
.. code:: bash
$ python ./setup.py extract_messages -o ./sphinx_rtd_theme/locale/sphinx.pot
.. tip::
More options please, check out http://babel.pocoo.org/en/latest/setup.html#extract-messages
Init catalog
------------
It creates a new translation catalog based on a PO template file (POT). Running the following
command will produce a PO file:
.. code:: bash
$ python ./setup.py init_catalog -l es -i ./sphinx_rtd_theme/locale/sphinx.pot \
-o ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po
.. tip::
More options please, check out http://babel.pocoo.org/en/latest/setup.html#init-catalog
Update catalog
--------------
It updates an existing translations catalog based on a PO template file (POT). Running the following
command will update a PO file:
.. code:: bash
$ python ./setup.py update_catalog -l es -i ./sphinx_rtd_theme/locale/sphinx.pot \
-o ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po
.. tip::
More options please, check out http://babel.pocoo.org/en/latest/setup.html#update-catalog
Compile catalog
---------------
It compile catalog an existing translations based on PO files into MO files. Running the following
command will compile catalog of PO files:
.. code:: bash
$ python ./setup.py compile_catalog -d ./sphinx_rtd_theme/locale/