Author vstinner
Recipients Maciej Olko, benjamin.peterson, docs@python, eric.araujo, ezio.melotti, mdk, ned.deily, python-dev, rhettinger, serhiy.storchaka, terry.reedy, vstinner, willingc, xtreak
Date 2020-06-24.16:47:39
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1593017259.94.0.0814427713736.issue40204@roundup.psfhosted.org>
In-reply-to
Content
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.
History
Date User Action Args
2020-06-24 16:47:40vstinnersetrecipients: + vstinner, rhettinger, terry.reedy, benjamin.peterson, ned.deily, ezio.melotti, eric.araujo, docs@python, python-dev, serhiy.storchaka, willingc, mdk, xtreak, Maciej Olko
2020-06-24 16:47:39vstinnersetmessageid: <1593017259.94.0.0814427713736.issue40204@roundup.psfhosted.org>
2020-06-24 16:47:39vstinnerlinkissue40204 messages
2020-06-24 16:47:39vstinnercreate