[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [56798] trunk/blender/source/blender/ python/intern/bpy_app_translations.c: API doc for bpy.app. translations should look better now.
Bastien Montagne
montagne29 at wanadoo.fr
Tue May 14 17:33:59 CEST 2013
Revision: 56798
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=56798
Author: mont29
Date: 2013-05-14 15:33:59 +0000 (Tue, 14 May 2013)
Log Message:
-----------
API doc for bpy.app.translations should look better now.
Modified Paths:
--------------
trunk/blender/source/blender/python/intern/bpy_app_translations.c
Modified: trunk/blender/source/blender/python/intern/bpy_app_translations.c
===================================================================
--- trunk/blender/source/blender/python/intern/bpy_app_translations.c 2013-05-14 14:37:51 UTC (rev 56797)
+++ trunk/blender/source/blender/python/intern/bpy_app_translations.c 2013-05-14 15:33:59 UTC (rev 56798)
@@ -300,12 +300,13 @@
"\n"
" Registers an addon's UI translations.\n"
"\n"
-" Note: Does nothing when Blender is built without internationalization support.\n"
+" .. note::\n"
+" Does nothing when Blender is built without internationalization support.\n"
"\n"
" :arg module_name: The name identifying the addon.\n"
" :type module_name: string\n"
" :arg translations_dict: A dictionary built like that:\n"
-" {locale: {msg_key: msg_translation, ...}, ...}\n"
+" ``{locale: {msg_key: msg_translation, ...}, ...}``\n"
" :type translations_dict: dict\n"
"\n"
);
@@ -347,7 +348,8 @@
"\n"
" Unregisters an addon's UI translations.\n"
"\n"
-" Note: Does nothing when Blender is built without internationalization support.\n"
+" .. note::\n"
+" Does nothing when Blender is built without internationalization support.\n"
"\n"
" :arg module_name: The name identifying the addon.\n"
" :type module_name: string\n"
@@ -433,8 +435,10 @@
PyDoc_STRVAR(app_translations_contexts_doc,
"A named tuple containing all pre-defined translation contexts.\n"
- "WARNING: Never use a (new) context starting with \"" BLF_I18NCONTEXT_DEFAULT_BPYRNA "\", it would be internally "
- "assimilated as the default one!\n"
+ "\n"
+ ".. warning::\n"
+ " Never use a (new) context starting with \"" BLF_I18NCONTEXT_DEFAULT_BPYRNA "\", it would be internally \n"
+ " assimilated as the default one!\n"
);
PyDoc_STRVAR(app_translations_contexts_C_to_py_doc,
@@ -530,18 +534,23 @@
".. method:: pgettext(msgid, msgctxt)\n"
"\n"
" Try to translate the given msgid (with optional msgctxt).\n"
-" NOTE: The (msgid, msgctxt) parameter orders has been switched compared to gettext function, to allow\n"
-" single-parameter calls (context then defaults to BLF_I18NCONTEXT_DEFAULT).\n"
-" NOTE: You should really rarely need to use this function in regular addon code, as all translation should be\n"
-" handled by Blender internal code. The only exception are string containing formatting (like \"File: %r\"),\n"
-" but you should rather use pgettext_iface/_tip in those cases!\n"
-" Note: Does nothing when Blender is built without internationalization support (hence always returns msgid).\n"
"\n"
+" .. note::\n"
+" The ``(msgid, msgctxt)`` parameters order has been switched compared to gettext function, to allow\n"
+" single-parameter calls (context then defaults to BLF_I18NCONTEXT_DEFAULT).\n"
+"\n"
+" .. note::\n"
+" You should really rarely need to use this function in regular addon code, as all translation should be\n"
+" handled by Blender internal code. The only exception are string containing formatting (like \"File: %r\"),\n"
+" but you should rather use :func:`pgettext_iface`/:func:`pgettext_tip` in those cases!\n"
+"\n"
+" .. note::\n"
+" Does nothing when Blender is built without internationalization support (hence always returns ``msgid``).\n"
+"\n"
" :arg msgid: The string to translate.\n"
" :type msgid: string\n"
-" :arg msgctxt: The translation context.\n"
+" :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
" :type msgctxt: string or None\n"
-" :default msgctxt: BLF_I18NCONTEXT_DEFAULT value.\n"
" :return: The translated string (or msgid if no translation was found).\n"
"\n"
);
@@ -554,13 +563,14 @@
".. method:: pgettext_iface(msgid, msgctxt)\n"
"\n"
" Try to translate the given msgid (with optional msgctxt), if labels' translation is enabled.\n"
-" NOTE: See pgettext notes.\n"
"\n"
+" .. note::\n"
+" See :func:`pgettext` notes.\n"
+"\n"
" :arg msgid: The string to translate.\n"
" :type msgid: string\n"
-" :arg msgctxt: The translation context.\n"
+" :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
" :type msgctxt: string or None\n"
-" :default msgctxt: BLF_I18NCONTEXT_DEFAULT value.\n"
" :return: The translated string (or msgid if no translation was found).\n"
"\n"
);
@@ -573,13 +583,14 @@
".. method:: pgettext_tip(msgid, msgctxt)\n"
"\n"
" Try to translate the given msgid (with optional msgctxt), if tooltips' translation is enabled.\n"
-" NOTE: See pgettext notes.\n"
"\n"
+" .. note::\n"
+" See :func:`pgettext` notes.\n"
+"\n"
" :arg msgid: The string to translate.\n"
" :type msgid: string\n"
-" :arg msgctxt: The translation context.\n"
+" :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
" :type msgctxt: string or None\n"
-" :default msgctxt: BLF_I18NCONTEXT_DEFAULT value.\n"
" :return: The translated string (or msgid if no translation was found).\n"
"\n"
);
@@ -592,14 +603,15 @@
".. method:: pgettext_data(msgid, msgctxt)\n"
"\n"
" Try to translate the given msgid (with optional msgctxt), if new data name's translation is enabled.\n"
-" NOTE: See pgettext notes.\n"
"\n"
+" .. note::\n"
+" See :func:`pgettext` notes.\n"
+"\n"
" :arg msgid: The string to translate.\n"
" :type msgid: string\n"
-" :arg msgctxt: The translation context.\n"
+" :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
" :type msgctxt: string or None\n"
-" :default msgctxt: BLF_I18NCONTEXT_DEFAULT value.\n"
-" :return: The translated string (or msgid if no translation was found).\n"
+" :return: The translated string (or ``msgid`` if no translation was found).\n"
"\n"
);
static PyObject *app_translations_pgettext_data(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
@@ -619,7 +631,7 @@
"\n"
" :arg locale: The ISO locale string to explode.\n"
" :type msgid: string\n"
-" :return: A tuple (language, country, variant, language_country, language at variant).\n"
+" :return: A tuple ``(language, country, variant, language_country, language at variant)``.\n"
"\n"
);
static PyObject *app_translations_locale_explode(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
@@ -693,27 +705,36 @@
}
PyDoc_STRVAR(app_translations_doc,
-" This object contains some data/methods regarding internationalization in Blender, and allows every py script\n"
-" to feature translations for its own UI messages.\n"
+"Intro\n"
+"-----\n"
"\n"
-" WARNING: Most of this object should only be useful if you actually manipulate i18n stuff from Python.\n"
-" If you are a regular addon, you should only bother about :contexts: and :context_sep: members, and the \n"
-" :register:/:unregister: functions!"
+"This object contains some data/methods regarding internationalization in Blender, and allows every py script\n"
+"to feature translations for its own UI messages.\n"
"\n"
-" To add translations to your python script, you must define a dictionary formatted like that:\n"
-" {locale: {msg_key: msg_translation, ...}, ...}\n"
-" where:\n"
-" locale is either a lang iso code (e.g. 'fr'), a lang+country code (e.g. 'pt_BR'),\n"
-" a lang+variant code (e.g. 'sr at latin'), or a full code (e.g. 'uz_UZ at cyrilic').\n"
-" msg_key is a tuple (context, org message) - use, as much as possible, the predefined :contexts:.\n"
-" msg_translation is the translated message in given language!"
-" Then, call bpy.app.translations.register(__name__, your_dict) in your register() function, and \n"
-" bpy.app.translations.unregister(__name__) in your unregister() one.\n"
+".. warning::\n"
+" Most of this object should only be useful if you actually manipulate i18n stuff from Python.\n"
+" If you are a regular addon, you should only bother about :const:`contexts` member, \n"
+" and the :func:`register`/:func:`unregister` functions!\n"
"\n"
-" bl_i18n_utils module has several functions to help you collect strings to translate, and generate the needed\n"
-" python code (the translation dictionary), as well as optional intermediary po files if you want some...\n"
-" See its documentation for more details.\n"
+"| To add translations to your python script, you must define a dictionary formatted like that:\n"
+"| ``{locale: {msg_key: msg_translation, ...}, ...}``\n"
+"| where:\n"
"\n"
+"* locale is either a lang iso code (e.g. ``fr``), a lang+country code (e.g. ``pt_BR``),\n"
+" a lang+variant code (e.g. ``sr at latin``), or a full code (e.g. ``uz_UZ at cyrilic``).\n"
+"* msg_key is a tuple (context, org message) - use, as much as possible, the predefined :const:`contexts`.\n"
+"* msg_translation is the translated message in given language!\n"
+"\n"
+"Then, call ``bpy.app.translations.register(__name__, your_dict)`` in your ``register()`` function, and \n"
+"``bpy.app.translations.unregister(__name__)`` in your ``unregister()`` one.\n"
+"\n"
+"``bl_i18n_utils`` module has several functions to help you collect strings to translate, and generate the needed\n"
+"python code (the translation dictionary), as well as optional intermediary po files if you want some...\n"
+"See its documentation for more details.\n"
+"\n"
+"Module References\n"
+"-----------------\n"
+"\n"
);
static PyTypeObject BlenderAppTranslationsType = {
PyVarObject_HEAD_INIT(NULL, 0)
More information about the Bf-blender-cvs
mailing list