FIX Format string defaults correctly

Before this patch, string defaults are formatted without quotes around
them. However, if the default is a tuple or list of strings, quotes will
be included:

  default="a" ==> :default: ``a``
  default=("a",) ==> :default: ``('a')``

This is a slightly annoying inconsistency, and leads to potential for
confusion between `default="0"` and `default=0`. Most bothersome is that
in the case of an empty string we get:

  :default: ````

Which makes docutils angry:

  CRITICAL: Unexpected section title or transition.

This fixes the trouble by formatting the repr of the default.

Author: hoodmane

releasenotes/notes/better-string-defaults-3664ae102b044972.yaml

@@ -0,0 +1,9 @@
+---
+features:
+  - |
+    Now when the default value of an option is a string it will be rendered with
+    quotes around it.
+fixes:
+  - |
+    If an option has an empty string default, docutils will no longer emit
+    warnings saying ``CRITICAL: Unexpected section title or transition.``

sphinx_click/ext.py

@@ -109,14 +109,14 @@ def _write_opts(opts: ty.List[str]) -> str:
         # Starting from Click 7.0 show_default can be a string. This is
         # mostly useful when the default is not a constant and
         # documentation thus needs a manually written string.
-        extras.append(':default: ``%s``' % show_default)
-    elif opt.default is not None and show_default:
+        extras.append(':default: ``%r``' % ANSI_ESC_SEQ_RE.sub('', show_default))
+    elif show_default and opt.default is not None:
         extras.append(
             ':default: ``%s``'
             % (
-                ', '.join(str(d) for d in opt.default)
+                ', '.join(repr(d) for d in opt.default)
                 if isinstance(opt.default, (list, tuple))
-                else opt.default,
+                else repr(opt.default),
             )
         )
 

tests/test_formatter.py

@@ -248,6 +248,8 @@ def test_defaults(self):
             '--only-show-default',
             show_default="Some default computed at runtime!",
         )
+        @click.option('--string-default', default="abc", show_default=True)
+        @click.option('--empty-string-default', default="", show_default=True)
         def foobar(bar):
             """A sample command."""
             pass
@@ -273,15 +275,23 @@ def foobar(bar):
 
         .. option:: --param <param>
 
-            :default: ``Something computed at runtime``
+            :default: ``'Something computed at runtime'``
 
         .. option:: --group <group>
 
             :default: ``('foo', 'bar')``
 
         .. option:: --only-show-default <only_show_default>
 
-            :default: ``Some default computed at runtime!``
+            :default: ``'Some default computed at runtime!'``
+
+        .. option:: --string-default <string_default>
+
+            :default: ``'abc'``
+
+        .. option:: --empty-string-default <empty_string_default>
+
+            :default: ``''``
         """
             ).lstrip(),
             '\n'.join(output),
@@ -438,7 +448,7 @@ def foobar():
 
         .. option:: --param <param>
 
-            :default: ``Something computed at runtime``
+            :default: ``'Something computed at runtime'``
 
         A sample epilog.
         """