API doc for bpy.app.translations should look better now.

1 files changed, 65 insertions, 44 deletions

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 = {