[Bf-committers] [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 20:14:49 CEST 2013


Done, thanks for the hint! :)

On 14/05/2013 18:02, Campbell Barton wrote:
> For longer, descriptive paragraphs of text, Id prefer to keep these
> out of the blender binary.
>
> You can use python scripts which will automatically get found and
> included by the document generator.
> Examples:
>
> doc/python_api/examples/bpy.types.ID.user_clear.1.py
> doc/python_api/examples/bpy.ops.py
>
> The initial comment is extracted and treated as an RST.
>
> Didn't check this works in the case of bpy.app.translations, but it
> could be made to work easy if support isn't there.
>
> On Wed, May 15, 2013 at 1:33 AM, Bastien Montagne<montagne29 at wanadoo.fr>  wrote:
>> 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)
>>
>> _______________________________________________
>> Bf-blender-cvs mailing list
>> Bf-blender-cvs at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-blender-cvs
>
>


More information about the Bf-committers mailing list