`doctest: +SKIP` is removed from incoming examples code when subclassing `MdRenderer`

[Phillip Cloud]

Hi!

Loving quartodoc. We're in the process of porting the ibis website over to quarto with quartodoc for API docs. Live demo here: https://ibis-quarto.netlify.app

One of the things we had to do was get @machow to help us with a custom renderer for docstring examples because the highlighting of some of our output was strange.

@machow built us a renderer that simply wraps the example in triple backticks with no python token.

This works well, but I think I figured out a more preferable solution: generate {python} blocks from the examples and have quarto run and render the output.

I have a working PR that looks really really nice IMO.

The main problem is that for doctests that I do not want to render with quarto I can't use doctest: +SKIP because that seems to be erased from the input code before rendering.

I invented some new tokens quartodoc: +SKIP (and quartodoc: +EXPECTED_FAILURE for the use case of rendering intended error messages) to solve this problem, but it feels like a hack.

Would it be possible to preserve doctest: +SKIP for the skip case, and figure out a proper solution for the expected failure case?

[Michael Chow]

Thanks for digging into this! @gforsyth and I chatted a bit about this at scipy, and in general it seems like running docstring examples is a huge win over having to manually code giant outputs doctest style!

Two quick notes:

• This has come up a bit in this issue, where @peekxc was looking into executing a whole section.
• It looks like the griffe parser has a default option (trim_doctest_flags) that removes doctest flags
  • I currently just hard-code parser options in parsers.py, and haven't exposed away for users to override yet, but we can likely modify in w/e way is most useful.

Do you mind recapping what's the most useful part of generating {python} blocks from examples is for you? Do you think you might eventually remove the hard-coded outputs in docstrings (similar to how R examples work, not hard-coded outputs)? Or is it more about getting nice formatting / output highlighting in the docs?

In any event, this work looks great! I'll be in a scramble for the next couple weeks with posit::conf, but would love to upstream something like this into quartodoc!

[Phillip Cloud]

Do you mind recapping what's the most useful part of generating {python} blocks from examples is for you?

Sure thing! See below.

Do you think you might eventually remove the hard-coded outputs in docstrings (similar to how R examples work, not hard-coded outputs)?

Probably not, because those are run with pytest --doctest-modules which unit tests the output. These pasted outputs are also necessary for users who look at docstrings from the command line (IPython, help, etc).

Or is it more about getting nice formatting / output highlighting in the docs?

It's pretty much exclusively about this.