Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Writing multi-language documentation using Sphinx

Writing multi-language documentation using Sphinx

How to write multi-language documentation? What tools can you use? What mistakes should you avoid? This talk is based on the experiences I gathered while working on several multi-language documentation projects using Sphinx.

Markus Zapke-Gründemann

July 23, 2014
Tweet

More Decks by Markus Zapke-Gründemann

Other Decks in Programming

Transcript

  1. Writing multi-language
    Documentation using Sphinx
    Markus Zapke-Gründemann
    EuroPython 2014

    View Slide

  2. Markus
    Zapke-Gründemann
    Software Developer since 2001
    Python, Django, Open Data and Training
    Owner of transcode
    Board member of the German Django
    Association
    keimlink.de // @keimlink

    View Slide

  3. Basics

    View Slide

  4. Sphinx
    Python Documentation Generator
    Markup Language: reStructuredText
    Output Formats: HTML, LaTeX (PDF), ePub, Texinfo, manual
    pages, plain text
    sphinx-doc.org

    View Slide

  5. Internationalization
    Often referred to as i18n
    Translating into other languages without changing the code
    GNU gettext is used frequently

    View Slide

  6. gettext Example
    import gettext
    t = gettext.translation('example', 'locale', fallback=True)
    _ = t.gettext
    print(_('Always look on the bright side of life'))

    View Slide

  7. Why use gettext for
    translated documentation?
    Untranslated strings are displayed in the
    source language
    Markup is not duplicated
    Professional translation tools can be used
    Contributions possible without using a VCS

    View Slide

  8. Sphinx
    Internationalization

    View Slide

  9. Sphinx i18n
    Workflow
    Source: http://sphinx-doc.org/intl.html

    View Slide

  10. Sphinx i18n
    Configuration
    docs/conf.py
    language = 'en'
    locale_dirs = ['locale/']
    # New in version 1.1
    gettext_compact = True

    View Slide

  11. sphinx-intl
    $ pip install sphinx-intl
    https://pypi.python.org/pypi/sphinx-intl

    View Slide

  12. sphinx-intl
    $ make gettext
    $ sphinx-intl update -l de -p _build/locale
    # Translate documentation
    $ sphinx-intl build
    $ make SPHINXOPTS="-Dlanguage=de" html

    View Slide

  13. Transifex

    View Slide

  14. www.transifex.com

    View Slide

  15. Transifex Setup
    $ pip install transifex-client
    $ tx init --user= --pass=

    View Slide

  16. Transifex and sphinx-intl
    $ sphinx-intl update-txconfig-resources \
    --pot-dir _build/locale \
    --transifex-project-name
    $ tx push -s
    # Translate documentation on Transifex
    $ tx pull -l de
    $ sphinx-intl build
    $ make SPHINXOPTS="-Dlanguage=de" html

    View Slide

  17. Handy tips
    for translating
    Sphinx documentation

    View Slide

  18. Using code inside
    the documentation
    All text inside the code should be English:
    !
    {% extends "marcador/bookmark_list.html" %}
    !
    {% block title %}{{ owner.username }}'s bookmarks{% endblock %}
    !
    {% block heading %}
    {{ owner.username }}'s bookmarks

    {{ bookmarks.count }} bookmarks in total

    {% endblock %}

    View Slide

  19. How to handle URLs
    Always use the inline syntax:
    !
    Alternatively, you can get the `Python Sources download/>`_ from the website and compile it
    yourself.
    !
    Because this way the URL will get lost:
    !
    Alternatively, you can get the `Python Sources`_ from the website
    and compile it yourself.
    !
    .. _Python Sources: http://python.org/download/

    View Slide

  20. How to maintain
    versoined URLs
    You can use the extlinks extension to define URLs in the configuration:
    !
    extlinks = {
    'djangodocs': ('https://docs.djangoproject.com/en/1.5/%s', None),
    'djangopdf': ('http://media.readthedocs.org/pdf/django/1.5.x/django.pdf%s', None)
    }
    !
    !
    You can find a list of all ``QuerySet`` methods in the :djangodocs:`documentation models/querysets/#queryset-api>`.
    !
    Download the :djangopdf:`Django Offline PDF Documentation <>` which has currently more
    than 1,200 pages.

    View Slide

  21. How to handle
    special cases
    ifconfig can be used to handle special cases:

    !
    .. ifconfig:: language == 'de'
    !
    Nützliche Links für deutschsprachige Django-Nutzer:
    !
    - `Deutschsprachige Django-Community `_

    View Slide

  22. Link checking
    You can check the links for each language separately:
    !
    $ make SPHINXOPTS="-Dlanguage=de" linkcheck

    View Slide

  23. What is still missing?
    A translations setting to build all languages
    with a single command
    A way to add a „landing page“
    Use gettext_compact to create a single catalog
    Collect all indices into a single .po file
    A language switch template

    View Slide

  24. Thanks!
    !
    www.transcode.de
    @keimlink

    View Slide