[docs] [issue28863] Doc/includes/*.py files and doctests

[Marco Buttu]

New submission from Marco Buttu:

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).

----------
assignee: docs at python
components: Documentation
messages: 282307
nosy: docs at python, marco.buttu
priority: normal
severity: normal
status: open
title: Doc/includes/*.py files and doctests
type: enhancement
versions: Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue28863>
_______________________________________