classification
Title: make *.rst files in Doc/ parseable by doctest
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, ezio.melotti
Priority: normal Keywords: patch

Created on 2012-09-13 13:41 by chris.jerdonek, last changed 2013-08-17 15:15 by ezio.melotti.

Files
File name Uploaded Description Edit
issue-15939-1.patch chris.jerdonek, 2012-09-13 15:10 review
issue15939-ctypes.diff ezio.melotti, 2012-10-11 13:28 Patch to fix doctests in ctypes against 3.2
issue15939-ctypes-2.diff ezio.melotti, 2013-08-17 15:15 Patch to fix doctests in ctypes against 3.4. review
Messages (8)
msg170441 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-13 13:41
Currently, when trying to parse the *.rst files in the Doc/ folder (i.e. not actually running them but simply generating unittest.TestCase instances from them by passing them to doctest.DocFileSuite()), five files yield errors.

This issue is to make it so that all of the *.rst files in our Doc/ folder are at least parseable by doctest without error.

I will submit a patch.

Below are the errors that currently occur:

(1) test fdoc:library/ctypes.rst crashed -- Traceback (most recent call last):
  ...
ValueError: line 55 of the doctest for ctypes.rst has an invalid option: '+WINDOWS'

(2) test fdoc:library/doctest.rst crashed -- Traceback (most recent call last):
  ...
ValueError: line 1592 of the docstring for doctest.rst has inconsistent leading whitespace: '      """))'

(3) test fdoc:library/multiprocessing.rst crashed -- Traceback (most recent call last):
  ...
ValueError: line 1016 of the docstring for multiprocessing.rst lacks blank after >>>: '>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>'

(4) test fdoc:whatsnew/2.4.rst crashed -- Traceback (most recent call last):
  ...
ValueError: line 1422 of the docstring for 2.4.rst lacks blank after >>>: '   >>>"""'

(5) test fdoc:whatsnew/2.7.rst crashed -- Traceback (most recent call last):
  ...
ValueError: line 1531 of the docstring for 2.7.rst lacks blank after   .: '      ...'
msg170444 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-13 13:53
The attached patch addresses all but Doc/library/ctypes.rst.

See the following python-dev e-mail for a question about how best to handle that case:

http://mail.python.org/pipermail/python-dev/2012-September/121721.html
msg170791 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-20 04:58
My opinion on the "+LINUX" and "+WINDOWS" doctest directives in Doc/library/ctypes.rst is simply to leave them alone for now.  We can make those errors go away in code when running doctest by adding no-op calls to doctest.register_optionflag() as below:

+doctest.register_optionflag('WINDOWS')
+doctest.register_optionflag('LINUX')

prior to constructing the doctest TestSuites.
msg172634 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-11 12:07
If they don't work I see no reasons to leave them there.
Either there's another way to run those tests on selected platforms that can be used instead, of if there's no way the tests should just be skipped.
msg172642 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-11 13:28
The attached patch fixes the doctests in Doc/library/ctypes.rst.
msg172664 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-11 16:59
> Either there's another way to run those tests on selected platforms that can be used instead

A way to do it could be to register new doctest directives that skip the marked test based on the value of sys.platform.  If we remove the directives, we lose that information and won't be able to do it anymore.
msg172669 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-10-11 17:56
> A way to do it could be to register new doctest directives that skip
> the marked test based on the value of sys.platform.

That can be done for 3.4+ only though.

> If we remove the directives, we lose that information and won't
> be able to do it anymore.

It actually seems quite easy to distinguish them.  At the beginning 'libc' is created either using cdll.msvcrt (on windows) or CDLL("libc.so.6") (on Linux).  There are examples that use windll and other Windows- or Linux-specific functions later on but it's usually quite evident.  If we get lost we can always dig in the history or just run the tests and see where they fail.

FTR there were a few actual errors that I fixed (mostly about bytes vs string).  I also removed unnecessary prints and added a few doctest directives to make some of the tests pass.  'from ctypes import *' is used quite frequently, and it would be better to change it, but I left it unchanged for now.  I also removed an obsolete warning about the doctest directives in the example because Sphinx hides them.
msg172671 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-11 18:25
> FTR there were a few actual errors that I fixed (mostly about bytes vs string).

Great!  Note that for the others, I was just trying to make the files parseable rather than passing.  Currently, doctest aborts out on the files I fixed without even attempting to run the examples.

> That can be done for 3.4+ only though.

Well, yes and no.  If there is a helper script to check documentation, it could be run on any branch regardless of whether the script is in source control.  For example, I was planning to write such a script (from the regrtest patch I put together before) to help me when checking people's patches to code snippets in the documentation.
History
Date User Action Args
2013-08-17 15:15:58ezio.melottisetfiles: + issue15939-ctypes-2.diff
type: enhancement
versions: - Python 3.2
2012-10-11 18:25:24chris.jerdoneksetmessages: + msg172671
2012-10-11 17:56:26ezio.melottisetmessages: + msg172669
2012-10-11 16:59:24chris.jerdoneksetmessages: + msg172664
2012-10-11 13:29:00ezio.melottisetfiles: + issue15939-ctypes.diff

stage: patch review
messages: + msg172642
versions: + Python 3.4
2012-10-11 12:07:37ezio.melottisetmessages: + msg172634
2012-09-20 04:58:17chris.jerdoneksetmessages: + msg170791
2012-09-20 04:52:27chris.jerdoneksetnosy: + ezio.melotti
2012-09-13 15:10:24chris.jerdoneksetfiles: + issue-15939-1.patch
2012-09-13 15:10:03chris.jerdoneksetfiles: - issue-15935-1.patch
2012-09-13 13:53:51chris.jerdoneksetfiles: + issue-15935-1.patch
keywords: + patch
messages: + msg170444
2012-09-13 13:41:34chris.jerdonekcreate