Internationalizes section handouts with Sphinx, reST, and gettext.

.gitignore

@@ -0,0 +1,2 @@
+# Sphinx output
+_build/

Makefile

@@ -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)

README.md

@@ -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

conf.py

@@ -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

handouts-html/de/html/.buildinfo

@@ -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

handouts-html/de/html/_sources/index.rst.txt

@@ -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*

handouts-html/de/html/_sources/section1/section1.rst.txt

@@ -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.