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<[email protected]> > 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@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,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@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" >> +".. 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@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 = { >> PyVarObject_HEAD_INIT(NULL, 0) >> >> _______________________________________________ >> Bf-blender-cvs mailing list >> [email protected] >> http://lists.blender.org/mailman/listinfo/bf-blender-cvs > > _______________________________________________ Bf-committers mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-committers
