[docs] [issue36675] Doctest directives and comments missing from code samples

[Terry J. Reedy]

Terry J. Reedy <tjreedy at udel.edu> added the comment:

Doctest directives in code examples should be suppressed everywhere *except* in the doctest.html examples showing how to use directives.  The patch only exposes them for doctest.html and not for ctypes or anywhere else.

They really should not be in the dir example code that I linked to.
https://docs.python.org/3/library/functions.html#dir
The problem there are the double comments with both a real comment and a directive.

https://devguide.python.org/documenting/#source-code does not say anything about '::' causing suppression of comments and ':' leaving them.  It is misleading in implying the '::' is required for a code block.

----------

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