comments in the examples

[samukweku]

Brief Description

some of the examples have comments like #doctest:... I dont think this should show in the final output

@ericmjl @thatlittleboy

[thatlittleboy]

Agreed on the point that they're quite out of place in the docs.

So I see two issues/potential discussion points here:

1. The doctest (run by pytest in the automated tests) will fail the example in the image you posted, without the # doctest: +NORMALIZE_WHITESPACE comment. So removing this "flag" in the docstring source is not really an option, unless we turn off doctests entirely, or there is some way to signal to doctest to normalize whitespace in this example.
2. If 1. is not an option, then I suppose the only other way to get it off the HTML output (compiled by mkdocs) is to do some form of preprocessing to remove the # doctest: ... strings after the tests have completed running. Probably via some shell script to modify the html files inside the site/ directory.

Option 2. seems more feasible, I'm just wondering whether I'm missing anything else here.

[thatlittleboy]

Okay, Turns out this removal of doctest flags is done automatically in Sphinx (they have a trim_doctest_flags option turned on by default).

I've raised a feature request to mkdocstrings here: https://github.com/mkdocstrings/mkdocstrings/issues/386

This would be the cleanest way to solve this issue, barring that we could write our own post-transformation script to parse the HTML output (as suggested in option 2).

[thatlittleboy]

Resolved in #1235