diff --git a/releasenotes/notes/better-string-defaults-3664ae102b044972.yaml b/releasenotes/notes/better-string-defaults-3664ae102b044972.yaml
new file mode 100644
index 0000000..7fedf2d
--- /dev/null
+++ b/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.``
diff --git a/sphinx_click/ext.py b/sphinx_click/ext.py
index d17c8e6..9070780 100644
--- a/sphinx_click/ext.py
+++ b/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),
)
)
diff --git a/tests/test_formatter.py b/tests/test_formatter.py
index a1dc70f..e688f2d 100644
--- a/tests/test_formatter.py
+++ b/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,7 +275,7 @@ def foobar(bar):
.. option:: --param
- :default: ``Something computed at runtime``
+ :default: ``'Something computed at runtime'``
.. option:: --group
@@ -281,7 +283,15 @@ def foobar(bar):
.. option:: --only-show-default
- :default: ``Some default computed at runtime!``
+ :default: ``'Some default computed at runtime!'``
+
+ .. option:: --string-default
+
+ :default: ``'abc'``
+
+ .. option:: --empty-string-default
+
+ :default: ``''``
"""
).lstrip(),
'\n'.join(output),
@@ -438,7 +448,7 @@ def foobar():
.. option:: --param
- :default: ``Something computed at runtime``
+ :default: ``'Something computed at runtime'``
A sample epilog.
"""