Supports `.. click:example::` and `.. click:run::` directives

[kdeldycke]

The canonical click documentation has a nice way of showing CLI code examples and their results by the way of custom .. click:example:: and .. click:run:: Sphinx directives.

See for instance how plain Python is wrapped with click:example and rendered as a syntax-highlighted block. The resulting call of that CLI is automatically executed and rendered by a simple reference to click:run.

This is powerful the same way doctest is, as it serves the dual purpose of documentation and testing (Sphinx will not compile on errors). It reduces the burden of maintaining up-to-date examples.

This issue is a proposition to add these directive to the sphinx-click project. With a name like this, it seems sphinx-click is the best home for this feature.

[kdeldycke]

These 2 directives are currently implemented by the Pallets-Sphinx-Themes project.

Here is how I just managed to use them in my click-extra project:

1. Add Pallets-Sphinx-Themes dependency
2. Add a little workaround in Sphinx's conf.py
3. And now you can use both .. click:example:: and .. click:run:: in your docs.

Note that both directives needs to resides in the same {eval-rst} MyST block.

It's kind of hackish but OK to me for the moment. By adding these directives to sphinx-click we can get rid of the somewhat awkward Pallets-Sphinx-Themes dependency.

[stephenfin]

No issues with adding these here but I'd rather not duplicate it and it seems the pallets folks are happy with them where they are. Perhaps a pointer in the README would be useful?

I'm going to close this as I don't think there's anything to be done here. If you'd like to duplicate the changes here or add said link to the README, please feel free to reopen this.

[kdeldycke]

OK no worries, I understand. And the pallets folks provided the feedback I was waiting for, so let's keep that issue closed.

Thanks @stephenfin for the reply! :)