[Python-Dev] __docformat__ scope
edloper at gradient.cis.upenn.edu
Thu Apr 22 21:35:49 EDT 2004
Pep 258  specifies that the __docformat__ variable should be used to
define the markup language used by docstrings in a module.
Recently, I got an RFE for epydoc requesting that a __docformat__ in a
package's __init__.py apply to the entire package . My first
reaction was that it was a good idea, but then I remembered a recent
discussion on python-dev, where there seemed to be a strong sentiment
that "from __future__ import absolute_import" should *not* have package
scope ; and I wondered if some of the same arguments would go against
applying __docformat__ to the entire package.
So... Should __docformat__ have package scope (with submodules/
subpackages possibly overriding it), or should it only apply to the
actual module that defines it?
Either way, PEP 258 should be updated to reflect the decision.
 pep 258 (Docutils Design Specification)
 epydoc RFE: __docformat__ for entire packages
More information about the Python-Dev