Migrate to Sphinx 1.0 C language constructs.
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst
index 737ef7c..59e5422 100644
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -63,41 +63,41 @@
How can I execute arbitrary Python statements from C?
-----------------------------------------------------
-The highest-level function to do this is :cfunc:`PyRun_SimpleString` which takes
+The highest-level function to do this is :c:func:`PyRun_SimpleString` which takes
a single string argument to be executed in the context of the module
``__main__`` and returns 0 for success and -1 when an exception occurred
(including ``SyntaxError``). If you want more control, use
-:cfunc:`PyRun_String`; see the source for :cfunc:`PyRun_SimpleString` in
+:c:func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in
``Python/pythonrun.c``.
How can I evaluate an arbitrary Python expression from C?
---------------------------------------------------------
-Call the function :cfunc:`PyRun_String` from the previous question with the
-start symbol :cdata:`Py_eval_input`; it parses an expression, evaluates it and
+Call the function :c:func:`PyRun_String` from the previous question with the
+start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it and
returns its value.
How do I extract C values from a Python object?
-----------------------------------------------
-That depends on the object's type. If it's a tuple, :cfunc:`PyTuple_Size`
-returns its length and :cfunc:`PyTuple_GetItem` returns the item at a specified
-index. Lists have similar functions, :cfunc:`PyListSize` and
-:cfunc:`PyList_GetItem`.
+That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size`
+returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified
+index. Lists have similar functions, :c:func:`PyListSize` and
+:c:func:`PyList_GetItem`.
-For strings, :cfunc:`PyString_Size` returns its length and
-:cfunc:`PyString_AsString` a pointer to its value. Note that Python strings may
-contain null bytes so C's :cfunc:`strlen` should not be used.
+For strings, :c:func:`PyString_Size` returns its length and
+:c:func:`PyString_AsString` a pointer to its value. Note that Python strings may
+contain null bytes so C's :c:func:`strlen` should not be used.
To test the type of an object, first make sure it isn't *NULL*, and then use
-:cfunc:`PyString_Check`, :cfunc:`PyTuple_Check`, :cfunc:`PyList_Check`, etc.
+:c:func:`PyString_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.
There is also a high-level API to Python objects which is provided by the
so-called 'abstract' interface -- read ``Include/abstract.h`` for further
details. It allows interfacing with any kind of Python sequence using calls
-like :cfunc:`PySequence_Length`, :cfunc:`PySequence_GetItem`, etc.) as well as
+like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc.) as well as
many other useful protocols.
@@ -106,7 +106,7 @@
You can't. Use ``t = PyTuple_New(n)`` instead, and fill it with objects using
``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of
-``o``, so you have to :cfunc:`Py_INCREF` it. Lists have similar functions
+``o``, so you have to :c:func:`Py_INCREF` it. Lists have similar functions
``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``. Note that you *must* set all
the tuple items to some value before you pass the tuple to Python code --
``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python value.
@@ -115,9 +115,9 @@
How do I call an object's method from C?
----------------------------------------
-The :cfunc:`PyObject_CallMethod` function can be used to call an arbitrary
+The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary
method of an object. The parameters are the object, the name of the method to
-call, a format string like that used with :cfunc:`Py_BuildValue`, and the
+call, a format string like that used with :c:func:`Py_BuildValue`, and the
argument values::
PyObject *
@@ -125,7 +125,7 @@
char *arg_format, ...);
This works for any object that has methods -- whether built-in or user-defined.
-You are responsible for eventually :cfunc:`Py_DECREF`\ 'ing the return value.
+You are responsible for eventually :c:func:`Py_DECREF`\ 'ing the return value.
To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the
file object pointer is "f")::
@@ -138,7 +138,7 @@
Py_DECREF(res);
}
-Note that since :cfunc:`PyObject_CallObject` *always* wants a tuple for the
+Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the
argument list, to call a function without arguments, pass "()" for the format,
and to call a function with one argument, surround the argument in parentheses,
e.g. "(i)".
@@ -189,7 +189,7 @@
attr = PyObject_GetAttrString(module, "<attrname>");
-Calling :cfunc:`PyObject_SetAttrString` to assign to variables in the module
+Calling :c:func:`PyObject_SetAttrString` to assign to variables in the module
also works.
@@ -270,16 +270,16 @@
In Python you can use the :mod:`codeop` module, which approximates the parser's
behavior sufficiently. IDLE uses this, for example.
-The easiest way to do it in C is to call :cfunc:`PyRun_InteractiveLoop` (perhaps
+The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` (perhaps
in a separate thread) and let the Python interpreter handle the input for
-you. You can also set the :cfunc:`PyOS_ReadlineFunctionPointer` to point at your
+you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` to point at your
custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c``
for more hints.
However sometimes you have to run the embedded Python interpreter in the same
thread as your rest application and you can't allow the
-:cfunc:`PyRun_InteractiveLoop` to stop while waiting for user input. The one
-solution then is to call :cfunc:`PyParser_ParseString` and test for ``e.error``
+:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one
+solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``
equal to ``E_EOF``, which means the input is incomplete). Here's a sample code
fragment, untested, inspired by code from Alex Farber::
@@ -310,8 +310,8 @@
}
Another solution is trying to compile the received string with
-:cfunc:`Py_CompileString`. If it compiles without errors, try to execute the
-returned code object by calling :cfunc:`PyEval_EvalCode`. Otherwise save the
+:c:func:`Py_CompileString`. If it compiles without errors, try to execute the
+returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the
input for later. If the compilation fails, find out if it's an error or just
more input is required - by extracting the message string from the exception
tuple and comparing it to the string "unexpected EOF while parsing". Here is a
@@ -463,8 +463,8 @@
7.x, in particular, provided a "python2" binary that is compiled with 4-byte
Unicode. This only causes the link failure if the extension uses any of the
``PyUnicode_*()`` functions. It is also a problem if an extension uses any of
-the Unicode-related format specifiers for :cfunc:`Py_BuildValue` (or similar) or
-parameter specifications for :cfunc:`PyArg_ParseTuple`.
+the Unicode-related format specifiers for :c:func:`Py_BuildValue` (or similar) or
+parameter specifications for :c:func:`PyArg_ParseTuple`.
You can check the size of the Unicode character a Python interpreter is using by
checking the value of sys.maxunicode: