diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py
index c54f3369a..41663a0cc 100644
--- a/sphinx/writers/html.py
+++ b/sphinx/writers/html.py
@@ -131,24 +131,40 @@ class HTMLTranslator(BaseTranslator):
def visit_desc_parameterlist(self, node):
self.body.append('(')
self.first_param = 1
+ self.optional_param_level = 0
+ # How many required parameters are left.
+ self.required_params_left = sum([isinstance(c, addnodes.desc_parameter)
+ for c in node.children])
self.param_separator = node.child_text_separator
def depart_desc_parameterlist(self, node):
self.body.append(')')
+ # If required parameters are still to come, then put the comma after
+ # the parameter. Otherwise, put the comma before. This ensures that
+ # signatures like the following render correctly (see issue #1001):
+ #
+ # foo([a, ]b, c[, d])
+ #
def visit_desc_parameter(self, node):
- if not self.first_param:
- self.body.append(self.param_separator)
- else:
+ if self.first_param:
self.first_param = 0
+ elif not self.required_params_left:
+ self.body.append(self.param_separator)
+ if self.optional_param_level == 0:
+ self.required_params_left -= 1
if not node.hasattr('noemph'):
self.body.append('')
def depart_desc_parameter(self, node):
if not node.hasattr('noemph'):
self.body.append('')
+ if self.required_params_left:
+ self.body.append(self.param_separator)
def visit_desc_optional(self, node):
+ self.optional_param_level += 1
self.body.append('[')
def depart_desc_optional(self, node):
+ self.optional_param_level -= 1
self.body.append(']')
def visit_desc_annotation(self, node):