Repository navigation
Support code fences within comments #46
Description
Often it is useful to run some code without having it display in the rendered markdown. Two such cases:
- Running some setup code. Yes, fixtures are a workaround but sometimes each file needs its own setup code so it doesn't make sense having a bunch of fixtures in
conftest.py. - Running assertions to test our code. Often, these assertions should be hidden from those reading the documentation.
I tried placing the following in my documentation but it isn't being detected?
<!--
```python continuation
assert something == something_else
```
-->
Any workarounds or fixes?
Activity
freider commentedon Apr 8, 2025
I agree something like this would be very useful. Similarly being able to inline fixture definitions in a markdown file itself (but having it hidden) would be quite nice.
The code fence is probably not being detected as a code fence in this case since it's in a comment block and just a block of text to the markdown parser, and I guess it could be ambiguous to a user if the comment should hide it from pytest-markdown-docs as well.
To enable it, we'd have to adjust the markdown parser to do a secondary pass on content within comment blocks. Maybe this could be selectively enabled using some
--markdown-docs-commentsflag, in case it would break something for someone who actually wants it to remain a commentIf you want to give it a stab I'd be happy to look at a contribution
freider commentedon Apr 9, 2025
Not sure, but maybe this is possible to do via custom MarkdownIt configuration? If so, you should be able to use the new
pytest_markdown_docs_markdown_ithook in v0.9.0 for this. See README.md - let us know if that works!