gh-107298: Document PyAPI_DATA() macro

[vstinner]

Document PyAPI_DATA(), and PyAPI_FUNC() and PyMODINIT_FUNC macros in Doc/c-api/intro.rst. This change fix Sphinx warnings in Doc/using/configure.rst.

• Issue: Fix Sphinx warnings in the C API documentation #107298

---

📚 Documentation preview 📚: https://cpython-previews--109129.org.readthedocs.build/

[vstinner]

cc @serhiy-storchaka@hugovk

I saw these Sphinx warnings on a PR which doesn't touch Doc/using/configure.rst, so it's surprising. I saw them on the PR: https://github.com/python/cpython/pull/109101/files

[hugovk]

I saw these Sphinx warnings on a PR which doesn't touch Doc/using/configure.rst, so it's surprising. I saw them on the PR: #109101 (files)

Yep, all Sphinx warnings are logging during docs builds, regardless of whether you touch the actual file.

For example, this PR has the remaining warnings for that file:

/home/runner/work/cpython/cpython/Doc/using/configure.rst:102: WARNING: py:mod reference target not found: _sqlite
/home/runner/work/cpython/cpython/Doc/using/configure.rst:198: WARNING: py:mod reference target not found: ensurepip._bundled
/home/runner/work/cpython/cpython/Doc/using/configure.rst:341: WARNING: py:mod reference target not found: _testcapi
/home/runner/work/cpython/cpython/Doc/using/configure.rst:475: WARNING: py:func reference target not found: sys.gettotalrefcount
/home/runner/work/cpython/cpython/Doc/using/configure.rst:497: WARNING: c:macro reference target not found: Py_SAFE_DOWNCAST()
/home/runner/work/cpython/cpython/Doc/using/configure.rst:524: WARNING: py:func reference target not found: sys.getobjects
/home/runner/work/cpython/cpython/Doc/using/configure.rst:608: WARNING: py:mod reference target not found: pyexpat

[hugovk]

Thanks! Little suggestion adding 3 x "the":

Suggested change

	macro should only be used in Python C API. Example::
	PyAPI_DATA(const unsigned long) Py_Version;
	.. c:macro:: PyAPI_FUNC(type)
	Declare a function with a return type *type* which should be exported by
	Python. The macro should only be used in Python C API. Example::
	PyAPI_FUNC(PyObject *) PyLong_FromLong(long);
	.. c:macro:: PyMODINIT_FUNC
	Declare an extension module ``PyInit`` initialization function. The return
	type is :c:expr:`PyObject*`. The macro should only be used in Python C API.
	macro should only be used in the Python C API. Example::
	PyAPI_DATA(const unsigned long) Py_Version;
	.. c:macro:: PyAPI_FUNC(type)
	Declare a function with a return type *type* which should be exported by
	Python. The macro should only be used in the Python C API. Example::
	PyAPI_FUNC(PyObject *) PyLong_FromLong(long);
	.. c:macro:: PyMODINIT_FUNC
	Declare an extension module ``PyInit`` initialization function. The return
	type is :c:expr:`PyObject*`. The macro should only be used in the Python C API.

[serhiy-storchaka]

Are PyAPI_FUNC() and PyAPI_DATA() purposed to be used in a third-party code at all?

[vstinner]

Are PyAPI_FUNC() and PyAPI_DATA() purposed to be used in a third-party code at all?

I wrote "The macro should only be used in Python C API." They should not be used outside Python code base.

[hugovk]

Then should we explicitly document them as "internal"?

Or not document at all and silence the warnings?

Which leads to a third question: why are other docs referring to internal things?

[vstinner]

Which leads to a third question: why are other docs referring to internal things?

There is no clear separation between public and internal APIs in the documentation.

But the internal API is almost not documented at all. So far, I only saw 2 functions: _PyBytes_Resize() and _PyTuple_Resize(). Last years, I removed mentions of many private C API functions like _Py_NewReference() or PyImport_Cleanup(). I even removed PyImport_Cleanup() from the public C API (I made it internal) :-)

I was surprised to see: https://docs.python.org/dev/library/test.html

The test package is meant for internal use by Python only. It is documented for the benefit of the core developers of Python. Any use of this package outside of Python’s standard library is discouraged as code mentioned here can change or be removed without notice between releases of Python.

One day, it was proposed to have a separated documentation for the internal APIs, but nobody proposed anything concrete.

Sometimes I wish I could document these internal APIs, but I cannot, since their documentation has no home!

[vstinner]

Or not document at all and silence the warnings?

I would be fine with that as well.

[vstinner]

Ok, I created the opposite change: PR #109236 removes links to these 3 macros.

[hugovk]

@serhiy-storchaka Which do you prefer?

[vstinner]

(I prefer to not document them, PR #109236.)

[hugovk]

Sounds good to me.

[vstinner]

I close this PR, let's continue the discussion in PR #109236.