[issue40204] Docs build error with Sphinx 3.0 due to invalid C declaration

[STINNER Victor]

STINNER Victor <vstinner at python.org> added the comment:

I look into this issue. It's quite complicated :-(

The Sphinx 3.0.0b1 changelog says:

* The C domain has been rewritten, with additional directives and roles. The existing ones are now more strict, resulting in new warnings.
* The C domain has been rewritten adding for example:

  * Cross-referencing respecting the current scope.
  * Possible to document anonymous entities.
  * More specific directives and roles for each type of entitiy, e.g., handling scoping of enumerators.
  * New role c:expr for rendering expressions and types in text.

The Python documentation has many issues:

* Doc/howto/instrumentation.rst: ".. c:function:: function__entry(str filename, str funcname, int lineno)" is not valid
  => replace "str" with "char*" and explain that "char*" must be read as "str"... The documentation is about DTrace functions, it's not C code.

* Doc/library/configparser.rst: "unique" is declared twice
  => the second declaration must have :noindex: marker

* ".. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL)": the "..., NULL" part is invalid in C => remove ", NULL"

* .. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET: a variable must be declared with its type, but PY_VECTORCALL_ARGUMENTS_OFFSET is macro
  => use ".. c:macro::" instead

* ".. c:var:: Py_BytesWarningFlag": the type is missing
  => ".. c:var:: int Py_BytesWarningFlag"

* Doc/c-api/call.rst: vectorcallfunc documentation is not properly indented.
  => fix indentation

* Doc/c-api/buffer.rst: the table with ".. c:macro:: PyBUF_INDIRECT" is wrong. Sphinx fails because PyBUF_SIMPLE is declared twice.
  => use ":c:macro:`PyBUF_INDIRECT`" instead

* :c:type:`PyObject\*` is invalid
  => use  :c:type:`PyObject*`

* ... there are many other errors :-(

PR 19397 fix some errors, but not all of them.

----------
nosy: +vstinner

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40204>
_______________________________________