From 465d84b7e72c9fe4a8907ee539f736ff576d9dd6 Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sun, 2 Jul 2017 15:37:31 +0300
Subject: [PATCH] docs/library: Add CPython docs xref to each pertinent module.

Cross-reference text/link is implemented as RST substitution, so easy to
consistently.
---
 docs/library/array.rst        |  3 +--
 docs/library/builtins.rst     | 10 ++++++++++
 docs/library/cmath.rst        |  2 ++
 docs/library/gc.rst           |  2 ++
 docs/library/math.rst         |  2 ++
 docs/library/sys.rst          |  2 ++
 docs/library/ubinascii.rst    |  2 ++
 docs/library/ucollections.rst |  2 ++
 docs/library/uhashlib.rst     |  2 ++
 docs/library/uheapq.rst       |  2 ++
 docs/library/uio.rst          |  2 ++
 docs/library/ujson.rst        |  2 ++
 docs/library/uos.rst          |  2 ++
 docs/library/ure.rst          |  2 ++
 docs/library/uselect.rst      |  2 ++
 docs/library/usocket.rst      |  5 ++---
 docs/library/ussl.rst         |  2 ++
 docs/library/ustruct.rst      |  3 +--
 docs/library/utime.rst        |  2 ++
 docs/library/uzlib.rst        |  2 ++
 docs/templates/replace.inc    |  8 +++++++-
 21 files changed, 53 insertions(+), 8 deletions(-)

diff --git a/docs/library/array.rst b/docs/library/array.rst
index f52b4b385e..d096c6ec48 100644
--- a/docs/library/array.rst
+++ b/docs/library/array.rst
@@ -4,8 +4,7 @@
 .. module:: array
    :synopsis: efficient arrays of numeric data
 
-See `Python array <https://docs.python.org/3/library/array.html>`_ for more
-information.
+|see_cpython_module| :mod:`python:array`.
 
 Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
 ``L``, ``q``, ``Q``, ``f``, ``d`` (the latter 2 depending on the
diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst
index 658d46ecd1..365248dc76 100644
--- a/docs/library/builtins.rst
+++ b/docs/library/builtins.rst
@@ -21,6 +21,8 @@ Functions and types
 
 .. class:: bytes()
 
+    |see_cpython| `python:bytes`.
+
 .. function:: callable()
 
 .. function:: chr()
@@ -174,6 +176,10 @@ Exceptions
 
 .. exception:: OSError
 
+    |see_cpython| `python:OSError`. MicroPython doesn't implement ``errno``
+    attribute, instead use the standard way to access exception arguments:
+    ``exc.args[0]``.
+
 .. exception:: RuntimeError
 
 .. exception:: StopIteration
@@ -182,8 +188,12 @@ Exceptions
 
 .. exception:: SystemExit
 
+    |see_cpython| `python:SystemExit`.
+
 .. exception:: TypeError
 
+    |see_cpython| `python:TypeError`.
+
 .. exception:: ValueError
 
 .. exception:: ZeroDivisionError
diff --git a/docs/library/cmath.rst b/docs/library/cmath.rst
index 465cf54ad3..59e4ec1722 100644
--- a/docs/library/cmath.rst
+++ b/docs/library/cmath.rst
@@ -4,6 +4,8 @@
 .. module:: cmath
    :synopsis: mathematical functions for complex numbers
 
+|see_cpython_module| :mod:`python:cmath`.
+
 The ``cmath`` module provides some basic mathematical functions for
 working with complex numbers.
 
diff --git a/docs/library/gc.rst b/docs/library/gc.rst
index abc8b7933f..c823aed3e6 100644
--- a/docs/library/gc.rst
+++ b/docs/library/gc.rst
@@ -4,6 +4,8 @@
 .. module:: gc
    :synopsis: control the garbage collector
 
+|see_cpython_module| :mod:`python:gc`.
+
 Functions
 ---------
 
diff --git a/docs/library/math.rst b/docs/library/math.rst
index 9d5cf7b4ba..a6f13d48c1 100644
--- a/docs/library/math.rst
+++ b/docs/library/math.rst
@@ -4,6 +4,8 @@
 .. module:: math
    :synopsis: mathematical functions
 
+|see_cpython_module| :mod:`python:math`.
+
 The ``math`` module provides some basic mathematical functions for
 working with floating-point numbers.
 
diff --git a/docs/library/sys.rst b/docs/library/sys.rst
index 09054becc4..0bec35cc90 100644
--- a/docs/library/sys.rst
+++ b/docs/library/sys.rst
@@ -4,6 +4,8 @@
 .. module:: sys
    :synopsis: system specific functions
 
+|see_cpython_module| :mod:`python:sys`.
+
 Functions
 ---------
 
diff --git a/docs/library/ubinascii.rst b/docs/library/ubinascii.rst
index a8d359eb47..0664d5b09d 100644
--- a/docs/library/ubinascii.rst
+++ b/docs/library/ubinascii.rst
@@ -4,6 +4,8 @@
 .. module:: ubinascii
    :synopsis: binary/ASCII conversions
 
+|see_cpython_module| :mod:`python:binascii`.
+
 This module implements conversions between binary data and various
 encodings of it in ASCII form (in both directions).
 
diff --git a/docs/library/ucollections.rst b/docs/library/ucollections.rst
index 4e9de9ac67..96de67acc4 100644
--- a/docs/library/ucollections.rst
+++ b/docs/library/ucollections.rst
@@ -4,6 +4,8 @@
 .. module:: ucollections
    :synopsis: collection and container types
 
+|see_cpython_module| :mod:`python:collections`.
+
 This module implements advanced collection and container types to
 hold/accumulate various objects.
 
diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst
index 6b9a764ba8..50ed658cc1 100644
--- a/docs/library/uhashlib.rst
+++ b/docs/library/uhashlib.rst
@@ -4,6 +4,8 @@
 .. module:: uhashlib
    :synopsis: hashing algorithms
 
+|see_cpython_module| :mod:`python:hashlib`.
+
 This module implements binary data hashing algorithms. The exact inventory
 of available algorithms depends on a board. Among the algorithms which may
 be implemented:
diff --git a/docs/library/uheapq.rst b/docs/library/uheapq.rst
index c17dac0675..f822f1e7f3 100644
--- a/docs/library/uheapq.rst
+++ b/docs/library/uheapq.rst
@@ -4,6 +4,8 @@
 .. module:: uheapq
    :synopsis: heap queue algorithm
 
+|see_cpython_module| :mod:`python:heapq`.
+
 This module implements the heap queue algorithm.
 
 A heap queue is simply a list that has its elements stored in a certain way.
diff --git a/docs/library/uio.rst b/docs/library/uio.rst
index 1239c6394e..7042a9e376 100644
--- a/docs/library/uio.rst
+++ b/docs/library/uio.rst
@@ -4,6 +4,8 @@
 .. module:: uio
    :synopsis: input/output streams
 
+|see_cpython_module| :mod:`python:io`.
+
 This module contains additional types of stream (file-like) objects
 and helper functions.
 
diff --git a/docs/library/ujson.rst b/docs/library/ujson.rst
index 724bc90ee1..0932d0ab55 100644
--- a/docs/library/ujson.rst
+++ b/docs/library/ujson.rst
@@ -4,6 +4,8 @@
 .. module:: ujson
    :synopsis: JSON encoding and decoding
 
+|see_cpython_module| :mod:`python:json`.
+
 This modules allows to convert between Python objects and the JSON
 data format.
 
diff --git a/docs/library/uos.rst b/docs/library/uos.rst
index 1e7f33161a..7c52c1eead 100644
--- a/docs/library/uos.rst
+++ b/docs/library/uos.rst
@@ -4,6 +4,8 @@
 .. module:: uos
    :synopsis: basic "operating system" services
 
+|see_cpython_module| :mod:`python:os`.
+
 The ``uos`` module contains functions for filesystem access and ``urandom``
 function.
 
diff --git a/docs/library/ure.rst b/docs/library/ure.rst
index 92f277af42..67f4f54a1d 100644
--- a/docs/library/ure.rst
+++ b/docs/library/ure.rst
@@ -4,6 +4,8 @@
 .. module:: ure
    :synopsis: regular expressions
 
+|see_cpython_module| :mod:`python:re`.
+
 This module implements regular expression operations. Regular expression
 syntax supported is a subset of CPython ``re`` module (and actually is
 a subset of POSIX extended regular expressions).
diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst
index a4026e98c3..e330207dbd 100644
--- a/docs/library/uselect.rst
+++ b/docs/library/uselect.rst
@@ -4,6 +4,8 @@
 .. module:: uselect
    :synopsis: wait for events on a set of streams
 
+|see_cpython_module| :mod:`python:select`.
+
 This module provides functions to efficiently wait for events on multiple
 streams (select streams which are ready for operations).
 
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index a52d4bf9a1..70d4f49fc2 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -5,10 +5,9 @@
 .. module:: usocket
    :synopsis: socket module
 
-This module provides access to the BSD socket interface.
+|see_cpython_module| :mod:`python:socket`.
 
-See the corresponding `CPython module <https://docs.python.org/3/library/socket.html>`_
-for comparison.
+This module provides access to the BSD socket interface.
 
 .. admonition:: Difference to CPython
    :class: attention
diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst
index 62b6db777b..c71b283ccb 100644
--- a/docs/library/ussl.rst
+++ b/docs/library/ussl.rst
@@ -4,6 +4,8 @@
 .. module:: ussl
    :synopsis: TLS/SSL wrapper for socket objects
 
+|see_cpython_module| :mod:`python:ssl`.
+
 This module provides access to Transport Layer Security (previously and
 widely known as “Secure Sockets Layer”) encryption and peer authentication
 facilities for network sockets, both client-side and server-side.
diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst
index a0a0ab65c0..81915d0a8d 100644
--- a/docs/library/ustruct.rst
+++ b/docs/library/ustruct.rst
@@ -4,8 +4,7 @@
 .. module:: ustruct
    :synopsis: pack and unpack primitive data types
 
-See `Python struct <https://docs.python.org/3/library/struct.html>`_ for more
-information.
+|see_cpython_module| :mod:`python:struct`.
 
 Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``.
 
diff --git a/docs/library/utime.rst b/docs/library/utime.rst
index 933e70ac57..a39f5ee733 100644
--- a/docs/library/utime.rst
+++ b/docs/library/utime.rst
@@ -4,6 +4,8 @@
 .. module:: utime
    :synopsis: time related functions
 
+|see_cpython_module| :mod:`python:time`.
+
 The ``utime`` module provides functions for getting the current time and date,
 measuring time intervals, and for delays.
 
diff --git a/docs/library/uzlib.rst b/docs/library/uzlib.rst
index 8775ec3e07..e531407b0f 100644
--- a/docs/library/uzlib.rst
+++ b/docs/library/uzlib.rst
@@ -4,6 +4,8 @@
 .. module:: uzlib
    :synopsis: zlib decompression
 
+|see_cpython_module| :mod:`python:zlib`.
+
 This modules allows to decompress binary data compressed with DEFLATE
 algorithm (commonly used in zlib library and gzip archiver). Compression
 is not yet implemented.
diff --git a/docs/templates/replace.inc b/docs/templates/replace.inc
index 6ed79cc7ce..1db89cb7e1 100644
--- a/docs/templates/replace.inc
+++ b/docs/templates/replace.inc
@@ -1 +1,7 @@
-.. # This file is intended for global "replace" definitions.
+.. comment: This file is intended for global "replace" definitions.
+
+.. |see_cpython_module| replace::
+
+    *This module implements a subset of the corresponding* `CPython` *module,
+    as described below. For more information, refer to the original
+    CPython documentation:*