Skip to content

Internationalizes section handouts with Sphinx, reST, and gettext. #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Sphinx output
_build/
19 changes: 19 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Minimal makefile for Sphinx documentation

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
89 changes: 89 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
Section Handouts (Code in Place 2020)
=====================================

[Code in Place](compedu.stanford.edu/codeinplace/v1/#/) is community-service coding education in the time of Covid-19.

Looking for Section Handouts?
-----------------------------

Click on any of the following links to go directly to the handout for your section.

*ENGLISH*

- Section 1: United Nations Karel

*ESPAÑOL*

- Section 1: United Nations Karel

*FRANÇAIS*

- Section 1: United Nations Karel

*DEUTSCHE*

- Section 1: United Nations Karel

Want to help with translations?
-------------------------------
Code in Place is fortunate to have students from several countries who speak several languages.

If you have the time, energy, and capacity, we would appreciate additional translations. To add a translation, modify a `.po` file in the `locale/` directory. Ideally, use a po-editor to help with formatting. Please be careful not to break reST notation.

Eventually, if desired, we'll move the open-source translation to Transifex [3], which is a friendlier interface for crowd-sourced translations.

**If you're a Code in Place student, you can stop reading now.**

What's up with Sphinx?
----------------------
Sphinx [1] is "a tool that makes it easy to create intelligent and beautiful
documentation" commonly used for writing about and documenting Python code.
It also has nice support for internationalization [2].

Preparing Documentation for Another Language
--------------------------------------------

First, hop into your virtual environment and install `sphinx` and `sphinx-intl`:

```
(venv) $ python3 -m pip install sphinx sphinx-intl
```

Make translation files for your target languages:

```bash
$ make gettext # Extract translatable messages into pot files.
$ sphinx-intl update -p _build/gettext -l es -l de -l fr # Generate `po` files from those `pot` files.
```

Then, somehow, the `.po` files need to be translated.

Once the `.po` files contain translations, we'll build the documentation in your desired language. For example, to build HTML documentation in Spanish, use:

```bash
$ make -e SPHINXOPTS="-D language='es'" html
```

To build PDF handouts, use:

```bash
$ make -e SPHINXOPTS="-D language='es'" latexpdf
```

That's pretty tough to remember, and each new language overwrites the old build output, so instead, use `makedoc.sh`.

```
$ ./makedoc.sh
```

It builds all of the documentation in HTML and PDF format and brings the build output to `handouts-html` and `handouts-pdf`.

Remember, whenever you add a new handout or change the existing documents, you need to update the PO files with the new content:

```bash
$ sphinx-intl update -p _build/gettext
```

[1]: https://www.sphinx-doc.org/
[2]: http://www.sphinx-doc.org/en/master/usage/advanced/intl.html
[3]: http://www.sphinx-doc.org/en/master/usage/advanced/intl.html#using-transifex-service-for-team-translation
69 changes: 69 additions & 0 deletions conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options.
# For a full list, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import pathlib

# -- Project information -----------------------------------------------------

project = 'Code in Place Section Handouts (2020)'
copyright = '2020, The Code in Place Teaching Team'
author = 'The Code in Place Teaching Team'

# The full version, including alpha/beta/rc tags
release = '0.0.1'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']


# -- Options for PDF output --------------------------------------------------
HERE = pathlib.Path(__file__).parent

# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_documents
latex_documents = [
(f'section{number}/section{number}', f'Section{number}.tex', f'Section {number}',
'Code in Place', 'howto')
for number in range(1, 10)
if (HERE / f'section{number}/section{number}.rst').exists()
]

# https://www.sphinx-doc.org/en/master/latex.html#the-latex-elements-configuration-setting
latex_elements = {
'maketitle': '', # Disable \maketitle
'tableofcontents': '' # Disable \tableofcontents
}


# -- Options for sphinx-intl -------------------------------------------------

locale_dirs = ['locale/']
gettext_compact = False
4 changes: 4 additions & 0 deletions handouts-html/de/html/.buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: db5fd44929727d1086e4772300c5ab81
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file added handouts-html/de/html/_images/final.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added handouts-html/de/html/_images/house.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added handouts-html/de/html/_images/initial.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions handouts-html/de/html/_sources/index.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
.. Code in Place Section Handouts (2020) documentation master file, created by
sphinx-quickstart on Sat Apr 11 19:14:41 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

=======================================
Section Handouts for Code in Place 2020
=======================================

.. toctree::
:maxdepth: 2
:caption: Handouts:
:titlesonly:
:glob:

section*/section*
42 changes: 42 additions & 0 deletions handouts-html/de/html/_sources/section1/section1.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
.. section1:

=================
Section Handout 1
=================

********************
United Nations Karel
********************

As part of its plans to help reconstruct infrastructure worldwide, the United Nations - that's right, the UN is using Karel - established a new program with the mission of dispatching house-building robots to repair flood-damaged areas.

Your job is to program those robots.

Each robot begins at the west end of a street that might look like this:

.. image:: img/initial.png
:alt: Initial World Layout for United Nations Karel
:align: center
:width: 100%

Each beeper in the figure represents a pile of debris. Karel's job is to walk along the street and build a new house in the places marked by each beeper. Those houses, moreover, need to be raised on stilts to avoid damage from the next flood. Each house, in fact, should look exactly like the picture below:

.. image:: img/house.png
:alt: A House made out of Beepers
:align: center
:width: 20%

The new house should be centered at the point at which the bit of debris was left, which means that the first house in the diagram above will be constructed with its left edge along 2nd Avenue. At the end of the run, Karel should be at the east end of the street having created a set of houses that look like this for the initial conditions shown:

.. image:: img/final.png
:alt: Final world layout for United Nations Karel
:align: center
:width: 100%

Keep in mind the following information about the world:

* Karel starts facing east at (1, 1) with an infinite number of beepers in its beeper bag.
* The beepers indicating the positions at which houses should be built will be spaced so that there is room to build the houses without overlapping or hitting walls.
* Karel must end up facing east at the southeast corner of the world. Moreover, Karel should not run into a wall if it builds a house that extends into that final corner.

Write a program to implement the United Nations Karel project. Remember that your program should work for any world that meets the above conditions.
Loading