cloup
cloup copied to clipboard
Use sphinx directive to generate output of full examples in the docs
Something like .. click:run::
directive.
https://github.com/pallets/pallets-sphinx-themes/blob/main/src/pallets_sphinx_themes/themes/click/domain.py
I just managed to do it in click-extra
. Here is how I did it:
-
Add
Pallets-Sphinx-Themes
dependency - Add a little workaround in Sphinx's
conf.py
- 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.
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.
Thanks for the useful info, @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.
FYI, I just streamlined and documented the setup of .. click:example::
and .. click:run::
directives at: https://kdeldycke.github.io/click-extra/sphinx.html