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@python
components: Documentation
messages: 282307
nosy: docs@python, marco.buttu
priority: normal
severity: normal
status: open
title: Doc/includes/*.py files and doctests
type: enhancement
versions: Python 3.7
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue28863>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
