[docs] Mark up of references in different form (issue 27036)
storchaka at gmail.com
storchaka at gmail.com
Mon May 16 16:34:49 EDT 2016
Reviewers: vadmium,
http://bugs.python.org/review/27036/diff/17256/Doc/library/asyncore.rst
File Doc/library/asyncore.rst (right):
http://bugs.python.org/review/27036/diff/17256/Doc/library/asyncore.rst#newcode104
Doc/library/asyncore.rst:104: :c:func:`polled <poll>` for read and write
events.
On 2016/05/16 11:38:10, vadmium wrote:
> Would it hurt to just drop the markup? As far as I know it normally
just changes
> the font, and doesn’t make a link.
Ah, I missed that this is just :c:func:. Maybe use references to
corresponding functions in the select module?
http://bugs.python.org/review/27036/diff/17256/Doc/library/email.headerregistry.rst
File Doc/library/email.headerregistry.rst (right):
http://bugs.python.org/review/27036/diff/17256/Doc/library/email.headerregistry.rst#newcode214
Doc/library/email.headerregistry.rst:214: ``decoded`` value is set by
:attr:`joining <~str.join>` the :class:`str` value of
On 2016/05/16 11:38:10, vadmium wrote:
> I think you would have to drop the tilde (~) to get the link to work.
There are
> other changes that also have this problem.
Good catch!
> But I don’t like this version any better than the original. What about
something
> like:
>
> . . . is set to the concatenation of the :class:`str` value
of each element
> . . ., using :meth:`str.join` and a separator of
``', '``.
I don't know. I left this for David. Maybe this sentence should be
merged with the first sentence in this paragraph.
http://bugs.python.org/review/27036/diff/17256/Doc/library/threading.rst
File Doc/library/threading.rst (right):
http://bugs.python.org/review/27036/diff/17256/Doc/library/threading.rst#newcode272
Doc/library/threading.rst:272: A thread can be :meth:`joined
<~Thread.join>` many times.
Since there are multiple references to Thread.join in surrounding
paragraphs, I think it is better to remove this reference.
http://bugs.python.org/review/27036/diff/17256/Doc/whatsnew/3.4.rst
File Doc/whatsnew/3.4.rst (right):
http://bugs.python.org/review/27036/diff/17256/Doc/whatsnew/3.4.rst#newcode1116
Doc/whatsnew/3.4.rst:1116: mmap objects can now be :mod:`weakrefed
<weakref>`. (Contributed by Valerie Lambert in
On 2016/05/16 11:38:10, vadmium wrote:
> Should probably be spelt “weakreffed” (refed means re-fed as in fed
again)
>
> Maybe “weakly referenced with :mod:`weakref` ”, or similar?
What about "mmap objects are now :mod:`weakly referenceable <weakref>`"?
Terms "weakly referenceable", "weak referenceable" and "weakly
referenced" are already used in the documentation.
See also yet one change in this file.
Please review this at http://bugs.python.org/review/27036/
Affected files:
Doc/library/array.rst
Doc/library/asyncore.rst
Doc/library/audioop.rst
Doc/library/base64.rst
Doc/library/binascii.rst
Doc/library/doctest.rst
Doc/library/email.headerregistry.rst
Doc/library/email.rst
Doc/library/hashlib.rst
Doc/library/http.cookies.rst
Doc/library/logging.config.rst
Doc/library/logging.rst
Doc/library/nntplib.rst
Doc/library/threading.rst
Doc/library/urllib.request.rst
Doc/whatsnew/3.4.rst
diff -r 3ceb54a49387 Doc/library/array.rst
--- a/Doc/library/array.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/array.rst Sat May 07 14:38:30 2016 +0300
@@ -91,7 +91,7 @@ Array objects support the ordinary seque
concatenation, and multiplication. When using slice assignment, the assigned
value must be an array object with the same type code; in all other cases,
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
-and may be used wherever :term:`bytes-like object`\ s are supported.
+and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
The following data items and methods are also supported:
diff -r 3ceb54a49387 Doc/library/asyncore.rst
--- a/Doc/library/asyncore.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/asyncore.rst Sat May 07 14:38:30 2016 +0300
@@ -100,8 +100,8 @@ any that have been added to the map duri
During asynchronous processing, each mapped channel's :meth:`readable` and
:meth:`writable` methods are used to determine whether the channel's socket
- should be added to the list of channels :c:func:`select`\ ed or
- :c:func:`poll`\ ed for read and write events.
+ should be added to the list of channels :c:func:`selected <select>` or
+ :c:func:`polled <poll>` for read and write events.
Thus, the set of channel events is larger than the basic socket events. The
full set of methods that can be overridden in your subclass follows:
diff -r 3ceb54a49387 Doc/library/audioop.rst
--- a/Doc/library/audioop.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/audioop.rst Sat May 07 14:38:30 2016 +0300
@@ -7,7 +7,7 @@
The :mod:`audioop` module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples 8, 16, 24
-or 32 bits wide, stored in :term:`bytes-like object`\ s. All scalar items are
+or 32 bits wide, stored in :term:`bytes-like objects <bytes-like object>`. All scalar items are
integers, unless specified otherwise.
.. versionchanged:: 3.4
diff -r 3ceb54a49387 Doc/library/base64.rst
--- a/Doc/library/base64.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/base64.rst Sat May 07 14:38:30 2016 +0300
@@ -40,7 +40,7 @@ package instead.
the modern interface.
.. versionchanged:: 3.4
- Any :term:`bytes-like object`\ s are now accepted by all
+ Any :term:`bytes-like objects <bytes-like object>` are now accepted by all
encoding and decoding functions in this module. Ascii85/Base85 support added.
The modern interface provides:
diff -r 3ceb54a49387 Doc/library/binascii.rst
--- a/Doc/library/binascii.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/binascii.rst Sat May 07 14:38:30 2016 +0300
@@ -21,7 +21,7 @@ higher-level modules.
.. note::
``a2b_*`` functions accept Unicode strings containing only ASCII characters.
- Other functions only accept :term:`bytes-like object`\ s (such as
+ Other functions only accept :term:`bytes-like objects <bytes-like object>` (such as
:class:`bytes`, :class:`bytearray` and other objects that support the buffer
protocol).
diff -r 3ceb54a49387 Doc/library/doctest.rst
--- a/Doc/library/doctest.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/doctest.rst Sat May 07 14:38:30 2016 +0300
@@ -464,12 +464,12 @@ Some details you should read once, but w
exception name is ignored.
* The interactive shell omits the traceback header line for some
- :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
+ :exc:`SyntaxErrors <SyntaxError>`. But doctest uses the traceback header line to
distinguish exceptions from non-exceptions. So in the rare case where you need
to test a :exc:`SyntaxError` that omits the traceback header, you will need to
manually add the traceback header line to your test example.
-* For some :exc:`SyntaxError`\ s, Python displays the character position of the
+* For some :exc:`SyntaxErrors <SyntaxError>`, Python displays the character position of the
syntax error, using a ``^`` marker::
>>> 1 1
@@ -1119,7 +1119,7 @@ the interactive examples extracted from
* :class:`Example`: A single Python :term:`statement`, paired with its expected
output.
-* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
+* :class:`DocTest`: A collection of :class:`Examples <Example>`, typically extracted
from a single docstring or text file.
Additional processing classes are defined to find, parse, and run, and check
@@ -1277,9 +1277,9 @@ DocTestFinder objects
.. class:: DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True)
- A processing class used to extract the :class:`DocTest`\ s that are relevant to
+ A processing class used to extract the :class:`DocTests <DocTest>` that are relevant to
a given object, from its docstring and the docstrings of its contained objects.
- :class:`DocTest`\ s can be extracted from modules, classes, functions,
+ :class:`DocTests <DocTest>` can be extracted from modules, classes, functions,
methods, staticmethods, classmethods, and properties.
The optional argument *verbose* can be used to display the objects searched by
@@ -1300,11 +1300,11 @@ DocTestFinder objects
.. method:: find(obj[, name][, module][, globs][, extraglobs])
- Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
+ Return a list of the :class:`DocTests <DocTest>` that are defined by *obj*'s
docstring, or by any of its contained objects' docstrings.
The optional argument *name* specifies the object's name; this name will be
- used to construct names for the returned :class:`DocTest`\ s. If *name* is
+ used to construct names for the returned :class:`DocTests <DocTest>`. If *name* is
not specified, then ``obj.__name__`` is used.
The optional parameter *module* is the module that contains the given object.
@@ -1370,8 +1370,8 @@ DocTestParser objects
.. method:: parse(string, name='<string>')
Divide the given string into examples and intervening text, and return them as
- a list of alternating :class:`Example`\ s and strings. Line numbers for the
- :class:`Example`\ s are 0-based. The optional argument *name* is a name
+ a list of alternating :class:`Examples <Example>` and strings. Line numbers for the
+ :class:`Examples <Example>` are 0-based. The optional argument *name* is a name
identifying this string, and is only used for error messages.
diff -r 3ceb54a49387 Doc/library/email.headerregistry.rst
--- a/Doc/library/email.headerregistry.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/email.headerregistry.rst Sat May 07 14:38:30 2016 +0300
@@ -211,7 +211,7 @@ headers.
The ``decoded`` value of the header will have all encoded words decoded to
unicode. :class:`~encodings.idna` encoded domain names are also decoded to unicode. The
- ``decoded`` value is set by :attr:`~str.join`\ ing the :class:`str` value of
+ ``decoded`` value is set by :attr:`joining <~str.join>` the :class:`str` value of
the elements of the ``groups`` attribute with ``', '``.
A list of :class:`.Address` and :class:`.Group` objects in any combination
diff -r 3ceb54a49387 Doc/library/email.rst
--- a/Doc/library/email.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/email.rst Sat May 07 14:38:30 2016 +0300
@@ -176,13 +176,13 @@ Here are the major differences between :
Problems found while parsing messages are stored in the message's *defect*
attribute.
-* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
+* All aspects of the API which raised :exc:`DeprecationWarnings <DeprecationWarning>` in version 2
have been removed. These include the *_encoder* argument to the
:class:`~email.mime.text.MIMEText` constructor, the
:meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
-* New :exc:`DeprecationWarning`\ s have been added to:
+* New :exc:`DeprecationWarnings <DeprecationWarning>` have been added to:
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
argument to the :class:`~email.parser.Parser` class. These are expected to
diff -r 3ceb54a49387 Doc/library/hashlib.rst
--- a/Doc/library/hashlib.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/hashlib.rst Sat May 07 14:38:30 2016 +0300
@@ -41,7 +41,7 @@ Hash algorithms
There is one constructor method named for each type of :dfn:`hash`. All return
a hash object with the same simple interface. For example: use :func:`sha1` to
create a SHA1 hash object. You can now feed this object with :term:`bytes-like
-object`\ s (normally :class:`bytes`) using the :meth:`update` method.
+objects <bytes-like object>` (normally :class:`bytes`) using the :meth:`update` method.
At any point you can ask it for the :dfn:`digest` of the
concatenation of the data fed to it so far using the :meth:`digest` or
:meth:`hexdigest` methods.
diff -r 3ceb54a49387 Doc/library/http.cookies.rst
--- a/Doc/library/http.cookies.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/http.cookies.rst Sat May 07 14:38:30 2016 +0300
@@ -109,7 +109,7 @@ Cookie Objects
.. method:: BaseCookie.load(rawdata)
If *rawdata* is a string, parse it as an ``HTTP_COOKIE`` and add the values
- found there as :class:`Morsel`\ s. If it is a dictionary, it is equivalent to::
+ found there as :class:`Morsels <Morsel>`. If it is a dictionary, it is equivalent to::
for k, v in rawdata.items():
cookie[k] = v
diff -r 3ceb54a49387 Doc/library/logging.config.rst
--- a/Doc/library/logging.config.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/logging.config.rst Sat May 07 14:38:30 2016 +0300
@@ -647,7 +647,7 @@ root logger section is given below. ::
The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or
``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be
-logged. Level values are :func:`eval`\ uated in the context of the ``logging``
+logged. Level values are :func:`evaluated <eval>` in the context of the ``logging``
package's namespace.
The ``handlers`` entry is a comma-separated list of handler names, which must
@@ -691,7 +691,7 @@ handler. If blank, a default formatter (
If a name is specified, it must appear in the ``[formatters]`` section and have
a corresponding section in the configuration file.
-The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
+The ``args`` entry, when :func:`evaluated <eval>` in the context of the ``logging``
package's namespace, is the list of arguments to the constructor for the handler
class. Refer to the constructors for the relevant handlers, or to the examples
below, to see how typical entries are constructed. ::
diff -r 3ceb54a49387 Doc/library/logging.rst
--- a/Doc/library/logging.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/logging.rst Sat May 07 14:38:30 2016 +0300
@@ -217,7 +217,7 @@ is the module's name in the Python packa
many contexts, and interesting conditions which arise are dependent on this
context (such as remote client IP address and authenticated user name, in the
above example). In such circumstances, it is likely that specialized
- :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
+ :class:`Formatters <Formatter>` would be used with particular :class:`Handlers <Handler>`.
.. versionadded:: 3.2
The *stack_info* parameter was added.
@@ -972,7 +972,7 @@ functions.
many contexts, and interesting conditions which arise are dependent on this
context (such as remote client IP address and authenticated user name, in the
above example). In such circumstances, it is likely that specialized
- :class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
+ :class:`Formatters <Formatter>` would be used with particular :class:`Handlers <Handler>`.
.. versionadded:: 3.2
The *stack_info* parameter was added.
diff -r 3ceb54a49387 Doc/library/nntplib.rst
--- a/Doc/library/nntplib.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/nntplib.rst Sat May 07 14:38:30 2016 +0300
@@ -68,7 +68,7 @@ The module itself defines the following
authentication is performed. Reader mode is sometimes necessary if you are
connecting to an NNTP server on the local machine and intend to call
reader-specific commands, such as ``group``. If you get unexpected
- :exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
+ :exc:`NNTPPermanentErrors <NNTPPermanentError>`, you might need to set *readermode*.
The :class:`NNTP` class supports the :keyword:`with` statement to
unconditionally consume :exc:`OSError` exceptions and to close the NNTP
connection when done, e.g.:
diff -r 3ceb54a49387 Doc/library/threading.rst
--- a/Doc/library/threading.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/threading.rst Sat May 07 14:38:30 2016 +0300
@@ -197,7 +197,7 @@ There is the possibility that "dummy thr
thread objects corresponding to "alien threads", which are threads of control
started outside the threading module, such as directly from C code. Dummy
thread objects have limited functionality; they are always considered alive and
-daemonic, and cannot be :meth:`~Thread.join`\ ed. They are never deleted,
+daemonic, and cannot be :meth:`joined <~Thread.join>`. They are never deleted,
since it is impossible to detect the termination of alien threads.
@@ -269,7 +269,7 @@ since it is impossible to detect the ter
When the *timeout* argument is not present or ``None``, the operation will
block until the thread terminates.
- A thread can be :meth:`~Thread.join`\ ed many times.
+ A thread can be :meth:`joined <~Thread.join>` many times.
:meth:`~Thread.join` raises a :exc:`RuntimeError` if an attempt is made
to join the current thread as that would cause a deadlock. It is also
diff -r 3ceb54a49387 Doc/library/urllib.request.rst
--- a/Doc/library/urllib.request.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/library/urllib.request.rst Sat May 07 14:38:30 2016 +0300
@@ -233,7 +233,7 @@ The following classes are provided:
.. class:: OpenerDirector()
- The :class:`OpenerDirector` class opens URLs via :class:`BaseHandler`\ s chained
+ The :class:`OpenerDirector` class opens URLs via :class:`BaseHandlers <BaseHandler>` chained
together. It manages the chaining of handlers, and recovery from errors.
diff -r 3ceb54a49387 Doc/whatsnew/3.4.rst
--- a/Doc/whatsnew/3.4.rst Sat May 07 10:49:58 2016 +0300
+++ b/Doc/whatsnew/3.4.rst Sat May 07 14:38:30 2016 +0300
@@ -1113,7 +1113,7 @@ with additional speedups by Antoine Pitr
mmap
----
-mmap objects can now be :mod:`weakref`\ ed. (Contributed by Valerie Lambert in
+mmap objects can now be :mod:`weakrefed <weakref>`. (Contributed by Valerie Lambert in
:issue:`4885`.)
@@ -1136,7 +1136,7 @@ the start method. (Contributed by Richa
determines how child processes are created. New function
:func:`~multiprocessing.get_context` returns a context that uses a specified
start method. It has the same API as the :mod:`multiprocessing` module itself,
-so you can use it to create :class:`~multiprocessing.pool.Pool`\ s and other
+so you can use it to create :class:`Pools <~multiprocessing.pool.Pool>` and other
objects that will operate within that context. This allows a framework and an
application or different parts of the same application to use multiprocessing
without interfering with each other. (Contributed by Richard Oudkerk in
@@ -1698,7 +1698,7 @@ will ensure that a given block of code e
:mod:`logging` module. By default the message can come from any logger and
have a priority of ``INFO`` or higher, but both the logger name and an
alternative minimum logging level may be specified. The object returned by the
-context manager can be queried for the :class:`~logging.LogRecord`\ s and/or
+context manager can be queried for the :class:`LogRecords <~logging.LogRecord>` and/or
formatted messages that were logged. (Contributed by Antoine Pitrou in
:issue:`18937`.)
@@ -2366,7 +2366,7 @@ Changes in the Python API
* :func:`base64.b32decode` now raises a :exc:`binascii.Error` when the
input string contains non-b32-alphabet characters, instead of a
:exc:`TypeError`. This particular :exc:`TypeError` was missed when the other
- :exc:`TypeError`\ s were converted. (Contributed by Serhiy Storchaka in
+ :exc:`TypeErrors <TypeError>` were converted. (Contributed by Serhiy Storchaka in
:issue:`18011`.) Note: this change was also inadvertently applied in Python
3.3.3.
More information about the docs
mailing list