diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index d9cabf90f8e29b1edb3f4b312589e9a54d77b526..2e63e4d4563d4b5a7253cfa229f9fc0b786475c8 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -249,7 +249,7 @@ Numbers
Convert a Python integer to a C :c:type:`unsigned long long`
without overflow checking.
-``n`` (:class:`int`) [Py_ssize_t]
+``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
Convert a Python integer to a C :c:type:`Py_ssize_t`.
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
@@ -576,7 +576,7 @@ Building values
``K`` (:class:`int`) [unsigned long long]
Convert a C :c:type:`unsigned long long` to a Python integer object.
- ``n`` (:class:`int`) [Py_ssize_t]
+ ``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
Convert a C :c:type:`Py_ssize_t` to a Python integer.
``c`` (:class:`bytes` of length 1) [char]
diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index d47f0422e6100482f45b0f8ddac0fb72012db3b7..7617487a462d37e3746977813d3cca548cb66970 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -84,8 +84,8 @@ called with a non-bytes parameter.
| :attr:`%lu` | unsigned long | Equivalent to |
| | | ``printf("%lu")``. [1]_ |
+-------------------+---------------+--------------------------------+
- | :attr:`%zd` | Py_ssize_t | Equivalent to |
- | | | ``printf("%zd")``. [1]_ |
+ | :attr:`%zd` | :c:type:`\ | Equivalent to |
+ | | Py_ssize_t` | ``printf("%zd")``. [1]_ |
+-------------------+---------------+--------------------------------+
| :attr:`%zu` | size_t | Equivalent to |
| | | ``printf("%zu")``. [1]_ |
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 9efac0b83d024d501ece3b21ced6d4587798b814..e53c826c58d13546cba6ca648bdfe42517b2fa46 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -537,6 +537,13 @@ data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that
use them.
+.. c:type:: Py_ssize_t
+
+ A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``.
+ C99 doesn't define such a thing directly (size_t is an unsigned integral type).
+ See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest positive value
+ of type :c:type:`Py_ssize_t`.
+
.. _api-exceptions:
diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 11c9c67d36a67865358909f46c3a30355dbf0e98..70b91f8c2d0ca17ad92094e9bcbb97065d57ef8f 100644
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -273,11 +273,11 @@ Number Protocol
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
- Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
+ Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be interpreted as an
integer. If the call fails, an exception is raised and ``-1`` is returned.
If *o* can be converted to a Python int but the attempt to
- convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
+ convert to a :c:type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the
*exc* argument is the type of exception that will be raised (usually
:exc:`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the
exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a negative
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 9dcfd769c64a05bb03dccb32a057da27be8b7784..07a625bac02fc4df11e9cfbcefd1835949e416dc 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -258,7 +258,7 @@ Object Protocol
.. versionchanged:: 3.2
The return type is now Py_hash_t. This is a signed integer the same size
- as Py_ssize_t.
+ as :c:type:`Py_ssize_t`.
.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 5e8d993100f6323f9ce68a3e4552a499b40d4a25..7b714678444be1210487481790eb8b77e352af86 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -348,7 +348,7 @@ accessible to C code. They all work with the current interpreter thread's
leaks.)
Note that ``#`` format characters should always be treated as
- ``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined.
+ :c:type:`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined.
:func:`sys.audit` performs the same function from Python code.
@@ -356,7 +356,7 @@ accessible to C code. They all work with the current interpreter thread's
.. versionchanged:: 3.8.2
- Require ``Py_ssize_t`` for ``#`` format characters. Previously, an
+ Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an
unavoidable deprecation warning was raised.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index ed434d8fd44fb2fb88f9d4da629681617f5dacce..b3f371bb9c0623aab5cc58659c5c104493d29e4f 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -43,13 +43,13 @@ Quick Reference
+================================================+===================================+===================+===+===+===+===+
| <R> :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
- | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X |
+ | :c:member:`~PyTypeObject.tp_basicsize` | :c:type:`Py_ssize_t` | | X | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
- | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X |
+ | :c:member:`~PyTypeObject.tp_itemsize` | :c:type:`Py_ssize_t` | | | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
- | :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X |
+ | :c:member:`~PyTypeObject.tp_vectorcall_offset` | :c:type:`Py_ssize_t` | | | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G |
| | | __getattr__ | | | | |
@@ -96,7 +96,7 @@ Quick Reference
| | | __gt__, | | | | |
| | | __ge__ | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
- | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? |
+ | :c:member:`~PyTypeObject.tp_weaklistoffset` | :c:type:`Py_ssize_t` | | | X | | ? |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
@@ -117,7 +117,7 @@ Quick Reference
| :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X |
| | | __delete__ | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
- | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? |
+ | :c:member:`~PyTypeObject.tp_dictoffset` | :c:type:`Py_ssize_t` | | | X | | ? |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
| :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+
@@ -333,7 +333,7 @@ slot typedefs
| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * |
| | | |
| | :c:type:`PyTypeObject` * | |
-| | Py_ssize_t | |
+| | :c:type:`Py_ssize_t` | |
+-----------------------------+-----------------------------+----------------------+
| :c:type:`destructor` | void * | void |
+-----------------------------+-----------------------------+----------------------+
@@ -405,7 +405,7 @@ slot typedefs
+-----------------------------+-----------------------------+----------------------+
| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * |
+-----------------------------+-----------------------------+----------------------+
-| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t |
+| :c:type:`lenfunc` | :c:type:`PyObject` * | :c:type:`Py_ssize_t` |
+-----------------------------+-----------------------------+----------------------+
| :c:type:`getbufferproc` | .. line-block:: | int |
| | | |
@@ -438,12 +438,12 @@ slot typedefs
| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * |
| | | |
| | :c:type:`PyObject` * | |
-| | Py_ssize_t | |
+| | :c:type:`Py_ssize_t` | |
+-----------------------------+-----------------------------+----------------------+
| :c:type:`ssizeobjargproc` | .. line-block:: | int |
| | | |
| | :c:type:`PyObject` * | |
-| | Py_ssize_t | |
+| | :c:type:`Py_ssize_t` | |
+-----------------------------+-----------------------------+----------------------+
| :c:type:`objobjproc` | .. line-block:: | int |
| | | |
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 6acd7ba790842bd4d2adb52cb878f5f51a1eee05..9dccbf1dc2298a9dd47c5c7efaec775084fccd58 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -436,11 +436,11 @@ APIs:
| :attr:`%llu` | unsigned long long | Equivalent to |
| | | ``printf("%llu")``. [1]_ |
+-------------------+---------------------+----------------------------------+
- | :attr:`%zd` | Py_ssize_t | Equivalent to |
- | | | ``printf("%zd")``. [1]_ |
+ | :attr:`%zd` | :c:type:`\ | Equivalent to |
+ | | Py_ssize_t` | ``printf("%zd")``. [1]_ |
+-------------------+---------------------+----------------------------------+
- | :attr:`%zi` | Py_ssize_t | Equivalent to |
- | | | ``printf("%zi")``. [1]_ |
+ | :attr:`%zi` | :c:type:`\ | Equivalent to |
+ | | Py_ssize_t` | ``printf("%zi")``. [1]_ |
+-------------------+---------------------+----------------------------------+
| :attr:`%zu` | size_t | Equivalent to |
| | | ``printf("%zu")``. [1]_ |
diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index 989527b6513759b89196bc34a47f15721e747efe..7959bc3a5c5b3eb936f3aebb62901f0b9d12dbab 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1347,7 +1347,7 @@ Here's the simplest example of a custom converter, from ``Modules/zlibmodule.c``
/*[python end generated code: output=da39a3ee5e6b4b0d input=35521e4e733823c7]*/
This block adds a converter to Argument Clinic named ``ssize_t``. Parameters
-declared as ``ssize_t`` will be declared as type ``Py_ssize_t``, and will
+declared as ``ssize_t`` will be declared as type :c:type:`Py_ssize_t`, and will
be parsed by the ``'O&'`` format unit, which will call the
``ssize_t_converter`` converter function. ``ssize_t`` variables
automatically support default values.
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 6b88cf66069198c9476f4f555e7e69c4d1d91321..c2f78f1531317a3b0c54165dbdb0d909d0941a8d 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -1493,7 +1493,7 @@ Optimizations
first introduced in Python 3.4. It offers better performance and smaller
size compared to Protocol 3 available since Python 3.0.
-* Removed one ``Py_ssize_t`` member from ``PyGC_Head``. All GC tracked
+* Removed one :c:type:`Py_ssize_t` member from ``PyGC_Head``. All GC tracked
objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes.
(Contributed by Inada Naoki in :issue:`33597`.)