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

[Cheryl Sabella]

Cheryl Sabella <cheryl.sabella at gmail.com> added the comment:

;tldr;   There is a global configuration flag to show all the doctest directives for all the docs that are built.  The default is to suppress the doctest directives.  If a global setting isn't desired, then each doctest example will have to be changed individually.


I've looked at the Sphinx documentation for this and there are a few points to reference. 

* `::` defines a Literal block in reST. [1]  A literal block doesn't do anything special except from the last paragraph is this section of the docs: 
   "Code highlighting can be enabled for these literal blocks on a document-wide basis using the `highlight` directive and on a project-wide basis using the `highlight_language` configuration option. The code-block directive can be used to set highlighting on a block-by-block basis. These directives are discussed later."  CPython has the `highlight-language` set to python3.  

* A doctest block does not need to be in a Literal Block. [2]  They are identified automatically. [3]  According to the doc, doctest directives are suppressed from presentation:

    Also, you can give inline doctest options, like in doctest:

    >>> datetime.date.now()   # doctest: +SKIP
    datetime.date(2008, 1, 1)

    They will be respected when the test is run, but stripped from presentation output.

* Any section (doesn't need the single colon (`:`) can have the `code-block` directive on it. [4]  The `code-block` directive can define the language for highlighting.  

Note that in the Sphinx doctest [4] documentation, there is a config option `trim_doctest_flags`, which is True by default.  Setting this to False will show all the doctest directives for all the doctests in the documentation.

The nice thing about the doc build recognizing a section as a doctest is that it adds the toggle in the upper right of the block to 'Hide the toggle and output' so that the example can be copy and pasted more easily.  Changing it into something other than a doctest (like using a `code-block` directive, takes away this option.  Using `trim_doctest_flags=False` retains the hide button.

Options:
1.  Change global setting to false to show all doctest directives.
2.  Change only the blocks where the doctest directives need to be shown, but this makes them lose the 'Hide prompt and output' button.
3.  Add a new option under 'code-block' to control the displaying of the doctest directives at the code-block level. This would override the global setting.  I think this option could be added locally, but may need to be done upstream in Sphinx.



[1] http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html#literal-blocks
[2] http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html#doctest-blocks
[3] http://www.sphinx-doc.org/en/stable/usage/extensions/doctest.html
[4] http://www.sphinx-doc.org/en/stable/usage/restructuredtext/directives.html#showing-code-examples

----------
nosy: +cheryl.sabella

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