merge

CHANGES

@@ -76,6 +76,9 @@ Bugs fixed
   versions for Python 2 and 3, and loading the appropriate version for the
   running Python version.
 
+* #1017: Be helpful and tell the user when the argument to :rst:dir:`option`
+  does not match the required format.
+
 Documentation
 -------------
 

sphinx/domains/std.py

@@ -27,8 +27,7 @@ from sphinx.util.compat import Directive
 
 
 # RE for option descriptions
-option_desc_re = re.compile(
-    r'((?:/|-|--)[-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)')
+option_desc_re = re.compile(r'((?:/|-|--)[-_a-zA-Z0-9]+)(\s*.*)')
 
 
 class GenericObject(ObjectDescription):
@@ -130,14 +129,23 @@ class Target(Directive):
 
 class Cmdoption(ObjectDescription):
     """
-    Description of a command-line option (.. cmdoption).
+    Description of a command-line option (.. option).
     """
 
     def handle_signature(self, sig, signode):
         """Transform an option description into RST nodes."""
         count = 0
         firstname = ''
-        for m in option_desc_re.finditer(sig):
+        for potential_option in sig.split(', '):
+            potential_option = potential_option.strip()
+            m = option_desc_re.match(potential_option)
+            if not m:
+                self.env.warn(
+                    self.env.docname,
+                    'Malformed option description %r, should '
+                    'look like "-opt args", "--opt args" or '
+                    '"/opt args"' % potential_option, self.lineno)
+                continue
             optname, args = m.groups()
             if count:
                 signode += addnodes.desc_addname(', ', ', ')

sphinx/themes/basic/static/basic.css_t

@@ -89,6 +89,7 @@ div.sphinxsidebar #searchbox input[type="submit"] {
 
 img {
     border: 0;
+    max-width: 100%;
 }
 
 /* -- search page ----------------------------------------------------------- */

sphinx/themes/epub/static/epub.css

@@ -92,6 +92,7 @@ div.sphinxsidebar input {
 
 img {
     border: 0;
+    max-width: 100%;
 }
 
 /* -- search page ----------------------------------------------------------- */