Migrate to Sphinx 1.0 C language constructs.
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index dbacedf..bb741fb 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -11,12 +11,12 @@
All Python objects ultimately share a small number of fields at the beginning
of the object's representation in memory. These are represented by the
-:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn,
+:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
by the expansions of some macros also used, whether directly or indirectly, in
the definition of all other Python objects.
-.. ctype:: PyObject
+.. c:type:: PyObject
All object types are extensions of this type. This is a type which
contains the information Python needs to treat a pointer to an object as an
@@ -26,88 +26,88 @@
macro.
-.. ctype:: PyVarObject
+.. c:type:: PyVarObject
- This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size`
+ This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
field. This is only used for objects that have some notion of *length*.
This type does not often appear in the Python/C API. It corresponds to the
fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
-These macros are used in the definition of :ctype:`PyObject` and
-:ctype:`PyVarObject`:
+These macros are used in the definition of :c:type:`PyObject` and
+:c:type:`PyVarObject`:
.. XXX need to document PEP 3123 changes here
-.. cmacro:: PyObject_HEAD
+.. c:macro:: PyObject_HEAD
This is a macro which expands to the declarations of the fields of the
- :ctype:`PyObject` type; it is used when declaring new types which represent
+ :c:type:`PyObject` type; it is used when declaring new types which represent
objects without a varying length. The specific fields it expands to depend
- on the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is
- not defined, and :cmacro:`PyObject_HEAD` expands to::
+ on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is
+ not defined, and :c:macro:`PyObject_HEAD` expands to::
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
- When :cmacro:`Py_TRACE_REFS` is defined, it expands to::
+ When :c:macro:`Py_TRACE_REFS` is defined, it expands to::
PyObject *_ob_next, *_ob_prev;
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
-.. cmacro:: PyObject_VAR_HEAD
+.. c:macro:: PyObject_VAR_HEAD
This is a macro which expands to the declarations of the fields of the
- :ctype:`PyVarObject` type; it is used when declaring new types which
+ :c:type:`PyVarObject` type; it is used when declaring new types which
represent objects with a length that varies from instance to instance.
This macro always expands to::
PyObject_HEAD
Py_ssize_t ob_size;
- Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own
- expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.
+ Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own
+ expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.
-.. cmacro:: PyObject_HEAD_INIT(type)
+.. c:macro:: PyObject_HEAD_INIT(type)
This is a macro which expands to initialization values for a new
- :ctype:`PyObject` type. This macro expands to::
+ :c:type:`PyObject` type. This macro expands to::
_PyObject_EXTRA_INIT
1, type,
-.. cmacro:: PyVarObject_HEAD_INIT(type, size)
+.. c:macro:: PyVarObject_HEAD_INIT(type, size)
This is a macro which expands to initialization values for a new
- :ctype:`PyVarObject` type, including the :attr:`ob_size` field.
+ :c:type:`PyVarObject` type, including the :attr:`ob_size` field.
This macro expands to::
_PyObject_EXTRA_INIT
1, type, size,
-.. ctype:: PyCFunction
+.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
- Functions of this type take two :ctype:`PyObject\*` parameters and return
+ Functions of this type take two :c:type:`PyObject\*` parameters and return
one such value. If the return value is *NULL*, an exception shall have
been set. If not *NULL*, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
reference.
-.. ctype:: PyCFunctionWithKeywords
+.. c:type:: PyCFunctionWithKeywords
Type of the functions used to implement Python callables in C that take
- keyword arguments: they take three :ctype:`PyObject\*` parameters and return
- one such value. See :ctype:`PyCFunction` above for the meaning of the return
+ keyword arguments: they take three :c:type:`PyObject\*` parameters and return
+ one such value. See :c:type:`PyCFunction` above for the meaning of the return
value.
-.. ctype:: PyMethodDef
+.. c:type:: PyMethodDef
Structure used to describe a method of an extension type. This structure has
four fields:
@@ -128,10 +128,10 @@
+------------------+-------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
-types, but they always return :ctype:`PyObject\*`. If the function is not of
-the :ctype:`PyCFunction`, the compiler will require a cast in the method table.
-Even though :ctype:`PyCFunction` defines the first parameter as
-:ctype:`PyObject\*`, it is common that the method implementation uses a the
+types, but they always return :c:type:`PyObject\*`. If the function is not of
+the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
+Even though :c:type:`PyCFunction` defines the first parameter as
+:c:type:`PyObject\*`, it is common that the method implementation uses a the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
@@ -145,27 +145,27 @@
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
- :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.
+ :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
- using :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.
+ using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
.. data:: METH_KEYWORDS
- Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.
+ Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
The function expects three parameters: *self*, *args*, and a dictionary of
all the keyword arguments. The flag is typically combined with
:const:`METH_VARARGS`, and the parameters are typically processed using
- :cfunc:`PyArg_ParseTupleAndKeywords`.
+ :c:func:`PyArg_ParseTupleAndKeywords`.
.. data:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
they are listed with the :const:`METH_NOARGS` flag. They need to be of type
- :ctype:`PyCFunction`. The first parameter is typically named *self* and will
+ :c:type:`PyCFunction`. The first parameter is typically named *self* and will
hold a reference to the module or object instance. In all cases the second
parameter will be *NULL*.
@@ -173,9 +173,9 @@
.. data:: METH_O
Methods with a single object argument can be listed with the :const:`METH_O`
- flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.
- They have the type :ctype:`PyCFunction`, with the *self* parameter, and a
- :ctype:`PyObject\*` parameter representing the single argument.
+ flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
+ They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
+ :c:type:`PyObject\*` parameter representing the single argument.
These two constants are not used to indicate the calling convention but the
@@ -219,7 +219,7 @@
than wrapper object calls.
-.. ctype:: PyMemberDef
+.. c:type:: PyMemberDef
Structure which describes an attribute of a type which corresponds to a C
struct member. Its fields are:
@@ -271,14 +271,14 @@
T_PYSSIZET Py_ssize_t
=============== ==================
- :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that
- :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and
- :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
- :cmacro:`T_OBJECT_EX` over :cmacro:`T_OBJECT` because :cmacro:`T_OBJECT_EX`
+ :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
+ :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
+ :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
+ :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
handles use of the :keyword:`del` statement on that attribute more correctly
- than :cmacro:`T_OBJECT`.
+ than :c:macro:`T_OBJECT`.
- :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for
- read-only access. Using :cmacro:`T_STRING` for :attr:`type` implies
- :cmacro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX`
+ :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for
+ read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
+ :c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to *NULL*).