Re: [Python-Dev] [Python-checkins] r88032 - in python/branches/py3k/Doc: c-api/code.rst howto/logging-cookbook.rst howto/logging.rst library/2to3.rst library/importlib.rst library/stdtypes.rst library/sys.rst reference/expressions.rst reference/simple_stmts.rst whatsnew/2.0.rst whatsnew/2.1.rst whatsnew/2.2.rst whatsnew/2.4.rst whatsnew/3.0.rst
On 1/15/2011 12:03 PM, georg.brandl wrote:
Fix a few doc errors, mostly undefined keywords.
I am not sure what you mean by 'undefined keyword', but
- integer. If there is no source code, return :keyword:`None`. If the + integer. If there is no source code, return ``None``. If the [etc]
you have seem to have systematically removed the :keyword: role from None, False, and True. Since Language Reference 2.3.1 Keywords defines them as keywords, the entry keyword The name of a keyword in Python. in 4.5. Inline markup, Additional Markup Constructs, should specify "except for None, False, or True, which should just be marked as code literal ``None``, etc.". Or perhaps "The name of a statement keyword (other than None, False, or True) in Python." If your rule is even more nuanced (only sometimes make an exception), please elucidate. --- Terry Jan Reedy
Am 15.01.2011 19:58, schrieb Terry Reedy:
On 1/15/2011 12:03 PM, georg.brandl wrote:
Fix a few doc errors, mostly undefined keywords.
I am not sure what you mean by 'undefined keyword', but
- integer. If there is no source code, return :keyword:`None`. If the + integer. If there is no source code, return ``None``. If the [etc]
you have seem to have systematically removed the :keyword: role from None, False, and True. Since Language Reference 2.3.1 Keywords defines them as keywords, the entry
keyword The name of a keyword in Python.
in 4.5. Inline markup, Additional Markup Constructs, should specify "except for None, False, or True, which should just be marked as code literal ``None``, etc.". Or perhaps "The name of a statement keyword (other than None, False, or True) in Python."
This section of "Documenting Python" should probably be rephrased.
If your rule is even more nuanced (only sometimes make an exception), please elucidate.
The rule is simple: :keyword:`...` generates a link. There is no corresponding link target, and therefore Sphinx generates a warning (which is new in 1.0.7, which fixed that bug.) As for why there is no link target: I think any Python programmer knows what None, True or False are. There is absolutely no need to create a link every time one of them is mentioned, which is pretty often, especially in the case of None. In contrast, take for example "the :keyword:`with` statement": this one is pretty new and many programmers might not be entirely certain what it was about; the link goes to the description of that statement. cheers, Georg
participants (2)
-
Georg Brandl -
Terry Reedy