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. """