click-option-group items not rendered correctly

[SurealCereal]

I'm using sphinx-click to render my documentation in HTML and Markdown, and have come across an incompatibility with the click-option-group library. The groups are rendered with internal names instead of the help records they expose.

RequiredMutuallyExclusiveOptionGroup are output in a strange way, for example:

The click-option-group creator responded:

It seems, sphinx-click ignores get_help_record method of Option class and re-implements it in ext: https://github.com/click-contrib/sphinx-click/blob/7a7240b54911e7de1f67d514165ddd01f9575967/sphinx_click/ext.py#L31

Unfortunately, this means that we cannot customize this behavior in sphinx-click ext and we lose any custom help formatting for the options in sphinx docs. We could create an issue in sphinx-click about it.

Is there a way to hide/disable output for this element, or support it?

The issue in click-option-group is here: https://github.com/click-contrib/click-option-group/issues/4

[espdev]

A temporary workaround: https://github.com/click-contrib/click-option-group/pull/5

[stephenfin]

As noted in the docstring of the _get_help_record function, the reimplementation of the function is necessary to work around issues with how Sphinx expects options to be formatted. It looks like click-option-group is also overriding this and there's a clash. Unfortunately I don't have any clever suggestions for how to work around this so I'm sorry, but I'll have to close this as a wontfix issue. If @espdev or anyone else has any clever ideas, I'll happily reopen this and review a PR.

[espdev]

@stephenfin

Currently, I do not see a better (or beautiful/elegant) solution. I could suggest using .. describe:: directive instead of .. option::, but in this case indexing and referencing will be lost. However, it looks not bad. Another way: we could implement a new directive in StandardDomain (.. click-option:: for example) without .. option:: limitations.

Here is a result after my crazy monkey patching sphinx-click code (it uses .. describe::, original get_help_record and some indent tricks for GroupedOption):

[coloursofnoise]

@stephenfin I would propose allowing click.Option implementations to add a sphinx_get_help_record method to be invoked by sphinx-click if present.

Definitely not an ideal solution, but it permits full customization by the application, as well as hopefully allowing some code reuse between the click and sphinx help functions.

The change would be in _format_option (Implemented here):

- opt_help = _get_help_record(opt)
+ if callable(getattr(opt.__class__, "sphinx_get_help_record", None)):
+     opt_help = opt.sphinx_get_help_record(_get_help_record)
+ else:
+     opt_help = _get_help_record(opt)

Passing _get_help_record as an argument allows the user to decide whether to modify the help text generated by sphinx-click, or to generate their own help text altogether.