[docs+comments] fixes and updates

frappe/templates/autodoc/macros.html

@@ -1,8 +1,9 @@
 {% macro automodule(name) %}
 {% for obj in frappe.automodule(name) %}
 	{% if obj.type=="function" %}
-		<p>{{ name }}.<b>{{ obj.name }}</b>({{ print_args(obj.args) }})</p>
-		<p style="margin-left: 20px;">{{ obj.docs|markdown }}</p>
+		<p class="docs-attr-name">
+			{{ name }}.<b>{{ obj.name }}</b>({{ print_args(obj.args) }})</p>
+		<div class="docs-attr-desc">{{ obj.docs|markdown }}</div>
 		<br>
 	{% endif %}
 {% endfor %}
@@ -10,6 +11,7 @@
 
 {% macro print_args(args) -%}
 <i>{% for arg in args[0] -%}
-	{{ arg }}{{ loop.index }}{% if not loop.last %}, {% endif %}
+	{%- set default_idx = args[3]|len - args[0]|len + (loop.index - 1) if args[3] else -1 -%}
+	{{ arg }}{% if default_idx >= 0 %}={{ args[3][default_idx] }}{% endif %}{% if not loop.last %}, {% endif %}
 	{%- endfor %}</i>
 {%- endmacro %}

frappe/templates/includes/comments.html

@@ -58,6 +58,7 @@ frappe.ready(function() {
 			comment: $("[name='comment']").val(),
 			comment_doctype: "{{ doctype }}",
 			comment_docname: "{{ name }}",
+			comment_type: "Comment",
 			page_name: "{{ pathname }}",
 		}
 

frappe/translate.py

@@ -129,7 +129,7 @@ def add_lang_dict(code):
 	return code
 
 def make_dict_from_messages(messages, full_dict=None):
-	"""Returns translated messages as a dict in Language specified in :attr:`frappe.local.lang`
+	"""Returns translated messages as a dict in Language specified in `frappe.local.lang`
 
 	:param messages: List of untranslated messages
 	"""
@@ -161,7 +161,7 @@ def get_full_dict(lang):
 	return frappe.cache().get_value("lang:" + lang, lambda:load_lang(lang))
 
 def load_lang(lang, apps=None):
-	"""Combine all translations from `.csv` files in all :term:`apps`"""
+	"""Combine all translations from `.csv` files in all `apps`"""
 	out = {}
 	for app in (apps or frappe.get_all_apps(True)):
 		path = os.path.join(frappe.get_pymodule_path(app), "translations", lang + ".csv")
@@ -180,7 +180,7 @@ def clear_cache():
 		cache.delete_value("translation_assets:" + lang)
 
 def get_messages_for_app(app):
-	"""Returns all messages (list) for a specified :term:`app`"""
+	"""Returns all messages (list) for a specified `app`"""
 	messages = []
 	modules = ", ".join(['"{}"'.format(m.title().replace("_", " ")) \
 		for m in frappe.local.app_modules[app]])
@@ -439,7 +439,7 @@ def rebuild_all_translation_files():
 def write_translations_file(app, lang, full_dict=None, app_messages=None):
 	"""Write a translation file for a given language.
 
-	:param app: :term:`app` for which translations are to be written.
+	:param app: `app` for which translations are to be written.
 	:param lang: Language code.
 	:param full_dict: Full translated langauge dict (optional).
 	:param app_messages: Source strings (optional).
@@ -456,7 +456,7 @@ def write_translations_file(app, lang, full_dict=None, app_messages=None):
 		app_messages, full_dict or get_full_dict(lang))
 
 def send_translations(translation_dict):
-	"""Append translated dict in :attr:`frappe.local.response`"""
+	"""Append translated dict in `frappe.local.response`"""
 	if "__messages" not in frappe.local.response:
 		frappe.local.response["__messages"] = {}
 

frappe/utils/autodoc.py

@@ -8,7 +8,7 @@ frappe.utils.autodoc
 Inspect elements of a given module and return its objects
 """
 
-import inspect, importlib
+import inspect, importlib, re
 
 def automodule(name):
 	attributes = []
@@ -28,5 +28,29 @@ def get_function_info(value, module_name):
 			"name": value.__name__,
 			"type": "function",
 			"args": inspect.getargspec(value),
-			"docs": docs
+			"docs": parse(docs)
 		}
+
+def parse(docs):
+	if ":param" in docs:
+		out, title_set = [], False
+		for line in docs.splitlines():
+			if ":param" in line and not title_set:
+				# add title and list
+				out.append("")
+				out.append("**Parameters:**")
+				out.append("")
+				title_set = True
+
+			if ":param" in line:
+				line = re.sub("\s*:param\s([^:]+):(.*)", "- **\g<1>** - \g<2>", line)
+
+			if title_set and not ":param" in line:
+				# marker for end of list
+				out.append("")
+
+			out.append(line)
+
+		docs = "\n".join(out)
+
+	return docs

frappe/website/css/website.css

@@ -468,3 +468,11 @@ a.active {
 }
 
 /* end - needs review */
+
+/* docs */
+.docs-attr-name {
+	font-size: 120%;
+}
+.docs-attr-desc {
+	padding-left: 30px;
+}

frappe/website/utils.py

@@ -32,6 +32,7 @@ def get_comment_list(doctype, name):
 	return frappe.db.sql("""select
 		comment, comment_by_fullname, creation, comment_by
 		from `tabComment` where comment_doctype=%s
+		and ifnull(comment_type, "Comment")="Comment"
 		and comment_docname=%s order by creation""", (doctype, name), as_dict=1) or []
 
 def get_home_page():