Cheryl Sabella <[email protected]> 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 <[email protected]>
<https://bugs.python.org/issue36675>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
