20130401 (Monday, 01 April 2013)

Multilingual user docs using Sphinx’s i18n

I worked on djangosite.utils.fablib to support an optional internationalized “user manual” per project. The new aliases emu, umu, imu and cmu do for /userdocs the same as the aliases em, um, im and cm do for the Python code.

The project’s fabfile must set env.languages to something like:

env.languages = 'fr nl de'.split()

The new method lino.core.model.Model.subclasses_graph() generates a graphviz directive which

Upgrade Sphinx from 1.1.3 to 1.2b1

Georg Brandl has released a new version of Sphinx and asked to test it. The upgrade itself was smooth:

> pip install -U Sphinx
Downloading/unpacking Sphinx from http://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.2b1.tar.gz#md5=67bea6df63be8e2a76ebedc76d8f71a3
  Downloading Sphinx-1.2b1.tar.gz (3.0MB): 3.0MB downloaded
  Running setup.py egg_info for package Sphinx

    warning: no files found matching 'README'
    no previously-included directories found matching 'doc\_build'
Requirement already up-to-date: Pygments>=1.2 in c:\python27\lib\site-packages (from Sphinx)
Requirement already up-to-date: Jinja2>=2.3 in c:\python27\lib\site-packages (from Sphinx)
Requirement already up-to-date: docutils>=0.7 in c:\python27\lib\site-packages (from Sphinx)
Installing collected packages: Sphinx
  Found existing installation: Sphinx 1.1.3
    Uninstalling Sphinx:
      Successfully uninstalled Sphinx
  Running setup.py install for Sphinx

    warning: no files found matching 'README'
    no previously-included directories found matching 'doc\_build'
    Installing sphinx-apidoc-script.py script to c:\Python27\Scripts
    Installing sphinx-apidoc.exe script to c:\Python27\Scripts
    Installing sphinx-build-script.py script to c:\Python27\Scripts
    Installing sphinx-build.exe script to c:\Python27\Scripts
    Installing sphinx-quickstart-script.py script to c:\Python27\Scripts
    Installing sphinx-quickstart.exe script to c:\Python27\Scripts
    Installing sphinx-autogen-script.py script to c:\Python27\Scripts
    Installing sphinx-autogen.exe script to c:\Python27\Scripts
Successfully installed Sphinx
Cleaning up...

I rebuilt the following sites:

• http://www.lino-framework.org/

• https://welfare-user.lino-framework.org

• https://welfare.lino-framework.org/

• http://site.lino-framework.org/index.html

• http://north.lino-framework.org/index.html

One little problem was because I had been using the fact that a hidden doctree was still visible in the sidebar. On http://www.lino-framework.org/ there is a heading “Suggestions du chef” which was a kind of manually written “best of” toctree. But the sidebar still was meant to show the official toctree. The new version forced me to remove the :hidden: and add a “Sitemap” section there. I think the new version is right, and I’ll remove my “Suggestions du chef” section soon.

ValueError: need more than 1 value to unpack

The following problem (which I didn’t yet report to the mailing list) is still not solved in Sphinx 1.2b1:

Traceback (most recent call last):
  File "setup.py", line 3, in <module>
    setup(**SETUP_INFO)
  File "c:\Python27\lib\distutils\core.py", line 152, in setup
    dist.run_commands()
  File "c:\Python27\lib\distutils\dist.py", line 953, in run_commands
    self.run_command(cmd)
  File "c:\Python27\lib\distutils\dist.py", line 972, in run_command
    cmd_obj.run()
  File "c:\Python27\lib\site-packages\babel-1.0dev_r661-py2.7.egg\babel\messages\frontend.py", line 577, in run
    template = read_po(infile)
  File "c:\Python27\lib\site-packages\babel-1.0dev_r661-py2.7.egg\babel\messages\pofile.py", line 220, in read_po
    _add_message()
  File "c:\Python27\lib\site-packages\babel-1.0dev_r661-py2.7.egg\babel\messages\pofile.py", line 173, in _add_message
    catalog[msgid] = message
  File "c:\Python27\lib\site-packages\babel-1.0dev_r661-py2.7.egg\babel\messages\catalog.py", line 617, in __setitem__
    self.mime_headers = _parse_header(message.string).items()
  File "c:\Python27\lib\site-packages\babel-1.0dev_r661-py2.7.egg\babel\messages\catalog.py", line 372, in _set_mime_headers
    value, tzoffset, _ = re.split('([+-]\d{4})$', value, 1)
ValueError: need more than 1 value to unpack

The exception happens in Babel because Sphinx’s gettext builder generates POT-Creation-Date headers without timezone information. The generated .pot files contain:

"POT-Creation-Date: 2013-04-01 07:09\n"

but it should be

"POT-Creation-Date: 2013-04-01 07:09+0300\n"

Workaround for me is to find line 160 of sphinx/builders/gettext.py (below a comment “XXX should supply tz”):

ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z'),

and to replace it by:

ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z+0300'), # Estonian summertime