Author terry.reedy
Recipients docs@python, eric.araujo, ezio.melotti, mdk, steven.daprano, terry.reedy, willingc
Date 2019-04-27.02:20:55
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1556331656.0.0.417950311645.issue36675@roundup.psfhosted.org>
In-reply-to
Content
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">&gt;&gt;&gt; </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.
History
Date User Action Args
2019-04-27 02:20:56terry.reedysetrecipients: + terry.reedy, ezio.melotti, eric.araujo, steven.daprano, docs@python, willingc, mdk
2019-04-27 02:20:56terry.reedysetmessageid: <1556331656.0.0.417950311645.issue36675@roundup.psfhosted.org>
2019-04-27 02:20:55terry.reedylinkissue36675 messages
2019-04-27 02:20:55terry.reedycreate