Terry J. Reedy <tjreedy@udel.edu> added the comment: I verified that the line in Doc/library/doctest.rst has the comment. " For example, this test passes::
print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] " However, the comment is omitted from the .html built on Windows by Sphinx 1.8.1. " <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">)))</span> ***html for comment should be here*** <span class="go">[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,</span> <span class="go">10, 11, 12, 13, 14, 15, 16, 17, 18, 19]</span> </pre></div> </div> " To me, this is a bug with building the .html for doctest.rst. Comments are preserved elsewhere. For instance, the code example for https://docs.python.org/3/library/functions.html#dir. The .rst file has " The resulting list is sorted alphabetically. For example:
>>> import struct >>> dir() # show the names in the module namespace # doctest: +SKIP " Both use 3-space colon + indents to mean 'example block'. The only difference is '::' versus ':'. https://devguide.python.org/documenting/#source-code says :: is required. idle.rst also has a code example with comments displayed (I just submitted a PR to not suppress color highlighting.) I leave it to the doc experts to discover why the comments are not included in doctest.html. ---------- nosy: +eric.araujo, ezio.melotti, terry.reedy, willingc stage: -> needs patch title: Doctest directives and comments not visible or missing from code samples -> Doctest directives and comments missing from code samples versions: +Python 2.7, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue36675> _______________________________________