diff --git a/releasenotes/notes/add-show_default-from-context-support-ab4aeffcc513502d.yaml b/releasenotes/notes/add-show_default-from-context-support-ab4aeffcc513502d.yaml new file mode 100644 index 0000000..cc743cf --- /dev/null +++ b/releasenotes/notes/add-show_default-from-context-support-ab4aeffcc513502d.yaml @@ -0,0 +1,7 @@ +--- +fixes: + - | + Added support for ``show_default`` as defined in click context settings. + This allows for option defaults to be rendered in the output. Consistent + with click version 8.1.x, ``show_default`` is overridden by + ``Command.show_default``. diff --git a/sphinx_click/ext.py b/sphinx_click/ext.py index 4454bc8..f398aad 100644 --- a/sphinx_click/ext.py +++ b/sphinx_click/ext.py @@ -63,7 +63,7 @@ def _get_usage(ctx: click.Context) -> str: return formatter.getvalue().rstrip('\n') # type: ignore -def _get_help_record(opt: click.Option) -> ty.Tuple[str, str]: +def _get_help_record(ctx: click.Context, opt: click.Option) -> ty.Tuple[str, str]: """Re-implementation of click.Opt.get_help_record. The variant of 'get_help_record' found in Click makes uses of slashes to @@ -99,12 +99,17 @@ def _write_opts(opts: ty.List[str]) -> str: extras = [] - if isinstance(opt.show_default, str): + if opt.show_default is not None: + show_default = opt.show_default + else: + show_default = ctx.show_default + + if isinstance(show_default, 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``' % opt.show_default) - elif opt.default is not None and opt.show_default: + extras.append(':default: ``%s``' % show_default) + elif opt.default is not None and show_default: extras.append( ':default: ``%s``' % ( @@ -165,9 +170,11 @@ def _format_usage(ctx: click.Context) -> ty.Generator[str, None, None]: yield '' -def _format_option(opt: click.Option) -> ty.Generator[str, None, None]: +def _format_option( + ctx: click.Context, opt: click.Option +) -> ty.Generator[str, None, None]: """Format the output for a `click.Option`.""" - opt_help = _get_help_record(opt) + opt_help = _get_help_record(ctx, opt) yield '.. option:: {}'.format(opt_help[0]) if opt_help[1]: @@ -196,7 +203,7 @@ def _format_options(ctx: click.Context) -> ty.Generator[str, None, None]: ] for param in params: - for line in _format_option(param): + for line in _format_option(ctx, param): yield line yield '' diff --git a/tests/test_formatter.py b/tests/test_formatter.py index 9b302c4..b55b9d9 100644 --- a/tests/test_formatter.py +++ b/tests/test_formatter.py @@ -282,6 +282,40 @@ def foobar(bar): '\n'.join(output), ) + def test_show_default(self): + """Validate formatting of show_default via context_settings.""" + + @click.command(context_settings={"show_default": True}) + @click.option('--no-set', default=0) + @click.option('--set-false', default=0, show_default=False) + def foobar(): + """A sample command.""" + pass + + ctx = click.Context(foobar, info_name='foobar', show_default=True) + output = list(ext._format_command(ctx, nested='short')) + self.assertEqual( + textwrap.dedent( + """ + A sample command. + + .. program:: foobar + .. code-block:: shell + + foobar [OPTIONS] + + .. rubric:: Options + + .. option:: --no-set + + :default: ``0`` + + .. option:: --set-false + """ + ).lstrip(), + '\n'.join(output), + ) + def test_hidden(self): """Validate a `click.Command` with the `hidden` flag."""