From 761850f3771c79b3f7ad6ebf8bd6f2a0399bd308 Mon Sep 17 00:00:00 2001 From: Bastien Montagne Date: Tue, 14 May 2013 15:33:59 +0000 Subject: API doc for bpy.app.translations should look better now. --- .../blender/python/intern/bpy_app_translations.c | 109 ++++++++++++--------- 1 file changed, 65 insertions(+), 44 deletions(-) (limited to 'source/blender/python/intern') diff --git a/source/blender/python/intern/bpy_app_translations.c b/source/blender/python/intern/bpy_app_translations.c index 6f042318de2..fd913192be8 100644 --- a/source/blender/python/intern/bpy_app_translations.c +++ b/source/blender/python/intern/bpy_app_translations.c @@ -300,12 +300,13 @@ PyDoc_STRVAR(app_translations_py_messages_register_doc, "\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 @@ PyDoc_STRVAR(app_translations_py_messages_unregister_doc, "\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 @@ static PyObject *app_translations_contexts_make(void) 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 @@ PyDoc_STRVAR(app_translations_pgettext_doc, ".. 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 @@ PyDoc_STRVAR(app_translations_pgettext_iface_doc, ".. 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 @@ PyDoc_STRVAR(app_translations_pgettext_tip_doc, ".. 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 @@ PyDoc_STRVAR(app_translations_pgettext_data_doc, ".. 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 @@ PyDoc_STRVAR(app_translations_locale_explode_doc, "\n" " :arg locale: The ISO locale string to explode.\n" " :type msgid: string\n" -" :return: A tuple (language, country, variant, language_country, language@variant).\n" +" :return: A tuple ``(language, country, variant, language_country, language@variant)``.\n" "\n" ); static PyObject *app_translations_locale_explode(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw) @@ -693,26 +705,35 @@ static void app_translations_free(void *obj) } 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" -"\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!" -"\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@latin'), or a full code (e.g. 'uz_UZ@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" -"\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" +"Intro\n" +"-----\n" +"\n" +"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" +".. 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" +"| 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@latin``), or a full code (e.g. ``uz_UZ@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 = { -- cgit v1.2.3