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
