classification
Title: Doc/includes/*.py files and doctests
Type: enhancement Stage:
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: duplicate
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, marco.buttu
Priority: normal Keywords: patch

Created on 2016-12-03 21:48 by marco.buttu, last changed 2016-12-07 18:48 by marco.buttu. This issue is now closed.

Files
File name Uploaded Description Edit
conf.py.patch marco.buttu, 2016-12-04 10:07 review
Messages (3)
msg282307 - (view) Author: Marco Buttu (marco.buttu) * Date: 2016-12-03 21:48
In the Doc/includes directory, some of the *.py file names have a dash character. For instance: Doc/includes/tzinfo-examples.py. I am trying to make all of the code examples pass the doctests, and I usually need to import from these files some code. Importing from these modules also allow us to test them, and I think that is important because their code is included in the documentation.

There are two problems:

1) I can not directly import them, because of the - character, so I have to use __import__('file-name') and write other ugly tricks. I can import them in the setuptests, so the reader will not see these imports, but it is still ugly, and in addition the code examples will be not complete, and the reader will not be able to try the code

2) the dash in the file names is un-pythonic. As the PEP 0008 says, the preferred way is to use underscores: "Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability."

In conclusion, I propose to change the Doc/includes/*.py file names, replacing the dash character with an underscore. If you agree, I will do it step by step: I will change each file name only when I will work with the related documentation and code examples. 

PS. To include these files in the code examples, I also need to add the Doc/includes directory to the sys.path (in conf.py).
msg282326 - (view) Author: Marco Buttu (marco.buttu) * Date: 2016-12-04 10:07
Here is the patch for the Sphinx conf.py file.
msg282652 - (view) Author: Marco Buttu (marco.buttu) * Date: 2016-12-07 18:48
I attached a patch in issue 27200 that makes all doctests pass, so I close here.
History
Date User Action Args
2016-12-07 18:48:42marco.buttusetstatus: open -> closed
resolution: duplicate
messages: + msg282652
2016-12-04 10:07:52marco.buttusetfiles: + conf.py.patch
keywords: + patch
messages: + msg282326
2016-12-03 21:48:05marco.buttucreate