Change by Karthikeyan Singaravelan : ---------- nosy: +mdk _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Change by Roundup Robot : ---------- keywords: +patch pull_requests: +13038 stage: needs patch -> patch review _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Éric Araujo added the comment: OP is about the documentation page for doctest itself! ---------- _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Cheryl Sabella 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#liter... [2] http://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html#docte... [3] http://www.sphinx-doc.org/en/stable/usage/extensions/doctest.html [4] http://www.sphinx-doc.org/en/stable/usage/restructuredtext/directives.html#s... ---------- nosy: +cheryl.sabella _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Change by Julien Palard : ---------- pull_requests: +15647 pull_request: https://github.com/python/cpython/pull/16024 _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Change by miss-islington : ---------- pull_requests: +15653 pull_request: https://github.com/python/cpython/pull/16030 _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Jim DeLaHunt added the comment: We discovered and fixed this same problem back in 2011-2012 with #12947 . That was apparently the source of the monkeypatch that was removed as "obselete code" on 2019-09-12. That old issue commentary has some suggestions about other workarounds. This includes adding explanatory text about the fact that doctest directives are missing from the examples which should be showing them. Maybe some of those workarounds would be effective for us now. ---------- nosy: +JDLH _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Julien Palard added the comment: New changeset c8a10d2fabff492ab352501c316baf5f2fc6510e by Julien Palard in branch 'master': bpo-36675: Doc: Reveal doctest directives (GH-23620) https://github.com/python/cpython/commit/c8a10d2fabff492ab352501c316baf5f2fc... ---------- _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Anthony Sottile added the comment: should the minimum sphinx version be bumped and/or this reverted: https://github.com/python/cpython/blob/f7f0ed59bcc41ed20674d4b2aa443d3b79e72... this change breaks, for example, sphinx 1.8.5 while building for ubuntu 20.04 The directive used here requires sphinx>=3.2.0 I notice some other attempts have been made to make the docs more compatible with sphinx 1.x in this release as well so there might be conflicting directions here: https://github.com/python/cpython/commit/b63a620014b67a6e63d10783149c41baaf5... ---------- nosy: +Anthony Sottile _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________

Jim DeLaHunt added the comment: My goodness, things get complex sometimes. If we cannot make Sphinx preserve doctest directives and comments, perhaps we should go back to the historical bug discussion to look at workarounds which we considered earlier. For instance, maybe we should modify the text surrounding the examples to explain that doctests directives should appear there, but that our tool chain currently removes them. At the moment, I see doctest directives in the doctest source code at: https://github.com/python/cpython/blob/master/Doc/library/doctest.rst#direct... which do not appear in the corresponding HTML output at: https://docs.python.org/3/library/doctest.html#directives How about rewording the text before each of those examples? Or maybe finding some way to show those examples as literal text which Sphinx won't modify, even if it is not formatted like Python code examples? By the way, the discussion of this same problem back in 2011-2012 is at #12947 . At that time, we applied a "monkey patch" to the Sphinx code. I haven't read the discussion closely enough to figure out if such a patch would help now. ---------- _______________________________________ Python tracker https://bugs.python.org/issue36675 _______________________________________