Pep 258 [1] 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 [2]. 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 [3]; 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.
-Edward
[1] pep 258 (Docutils Design Specification)
http://www.python.org/peps/pep-0258.html
[2] epydoc RFE: __docformat__ for entire packages
http://sourceforge.net/tracker/index.php?func=detail&aid=928058&group_id=32455&atid=405621
[3] http://mail.python.org/pipermail/python-dev/2004-April/044201.html
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4