Организация перевода документации на основе Sphinx и Gettext

Дмитрий Косточко

Организация перевода документации на основе Sphinx и Gettext

Дмитрий Косточко

Где найти

Важность документации

Документация - как секс: если она хороша, то это очень хорошо; а если она плохая, то это всё же лучше чем ничего.

Дик Брэндон

Инструменты для представления и организации документации

Требования к инструменту для создания документации

Документация Django

С чего все началось

Перевод "The Django Book" для Django 1.0.
http://www.djangobook.com/

Docbook

			<chapter lang="ru" id="&BASEID;">
			  <title id="&BASEID;.title">Введение в Django</title>
			  <section id="&BASEID;.whatis">
			   <para>
			      Django является видным представителем нового поколения
			      <emphasis>сред разработки</emphasis>, но что же конкретно
			      подразумевают под этим термином?
			    </para>
			  </section>
			</chapter>

Как бы нам переводить документацию Django?

Выход Sphinx 1.1

Added i18n support for content, a gettext builder and related utilities.

Release notes Sphinx 1.1 (Oct 9, 2011)

Sphinx

Инструмент для создания документации на reStructuredText. C открытым исходным кодом. BSD лицензия. Построен на базе Docutils для документирования Python.

Cheers for a great tool that actually makes programmers want to write documentation!

What users say

reStructuredText

Облегчённый язык разметки. Используется в системе подготовки технической документации Docutils

Описание http://sphinx-doc.org/rest.html

			=====================================

			Writing your first Django app, part 1

			=====================================

			

			It'll consist of two parts:

			

			* A public site that lets people view polls and vote in them.

			* An admin site that lets you add, change and delete polls.

			

			We'll assume you have :doc:`Django installed </intro/install>` already. You can
			tell Django is installed and which version by running the following command:

			

			.. code-block:: bash

			

			    python -c "import django; print(django.get_version())"

Генерация в различные форматы

Документирование кода

			.. py:function:: send_message(message, [priority=1])
			
			   Send a message to a recipient
			
			   :param str message: The body of the message
			   :param priority: The priority of the message, can be a number 1-5
			   :type priority: integer or None
			   :return: the message id
			   :raises ValueError: if the message exceeds 160 characters
			   :raises TypeError: if the message is not a basestrinдg

Поддержка различных языков программирования

Autodoc

Генерация описания кода из docstrings.

			.. automodule:: io
			   :members:

Можно ссылаться на описание функций из внешней документации.

			:py:func:`io.open`

sphinx-apidoc

Создает с нуля документацию API используя docstrings.

			$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

Еще фичи

Gettext

Библиотека проекта GNU для интернационализации, широко применяемая в свободном ПО. 
			print(_("Hello! My name is %s.") % name)
			 
		
			#: src/main.py:36
			msgid "Hello! My name is %s."
			msgstr "Привет! Меня зовут %s."
		
			Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0
			: n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)
		
			msgid "%d day ago"
			msgid_plural "%d days ago"
			msgstr[0] "%d день назад"
			msgstr[1] "%d дня назад"
			msgstr[2] "%d дней назад"

Процесс перевода

Процесс обновления перевода с выходом новой версии Django

Развитие инструмента для организации перевода

Инструменты для перевода

Transifex

Краудсорсинговая платформа для управления локализацией.

https://www.transifex.com/

Read the Docs

Хостинг документации для открытых проектов.
https://readthedocs.org/

Fork me on Github