[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.
Campbell Barton
ideasman42 at gmail.com
Tue May 14 18:02:11 CEST 2013
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
--
- Campbell
More information about the Bf-committers
mailing list