[issue36675] Doctest directives and comments missing from code samples

[Jim DeLaHunt]

Jim DeLaHunt <from+python at jdlh.com> added the comment:

My goodness, things get complex sometimes. 

If we cannot make Sphinx preserve doctest directives and comments, perhaps we should go back to the historical bug discussion to look at workarounds which we considered earlier. For instance, maybe we should modify the text surrounding the examples to explain that doctests directives should appear there, but that our tool chain currently removes them.

At the moment, I see doctest directives in the doctest source code at: 
https://github.com/python/cpython/blob/master/Doc/library/doctest.rst#directives 
which do not appear in the corresponding HTML output at:
https://docs.python.org/3/library/doctest.html#directives 

How about rewording the text before each of those examples? Or maybe finding some way to show those examples as literal text which Sphinx won't modify, even if it is not formatted like Python code examples?

By the way, the discussion of this same problem back in 2011-2012 is at #12947 . At that time, we applied a "monkey patch" to the Sphinx code. I haven't read the discussion closely enough to figure out if such a patch would help now.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue36675>
_______________________________________