Use sphinx directive to generate output of full examples in the docs

[janluke]

Something like .. click:run:: directive.

https://github.com/pallets/pallets-sphinx-themes/blob/main/src/pallets_sphinx_themes/themes/click/domain.py

[kdeldycke]

I just managed to do it in click-extra. Here is how I did it:

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 as it lighten up a bit the burden of documentation maintenance.

[kdeldycke]

For the record, I added a bug report to the sphinx-click project to implement this feature instead of having it embedded within the Pallets-Sphinx-Themes project.

[janluke]

Thanks for the useful info, @kdeldycke!

[kdeldycke]

I just made something really cool for the upcoming click-extra v3.0.0 release: I managed to have the .. click:run:: directive output ANSI colored shell session in Pygments. It's a little janky but does the job.

[kdeldycke]

FYI, I just streamlined and documented the setup of .. click:example:: and .. click:run:: directives at: https://kdeldycke.github.io/click-extra/sphinx.html