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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
