bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901) (GH-21928)

* bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844)

Enable Sphinx 3.2 "c_allow_pre_v3" option and disable the
c_warn_on_allowed_pre_v3 option to make the documentation compatible
with Sphinx 2 and Sphinx 3.

(cherry picked from commit 423e77d6de497931585d1883805a9e3fa4096b0b)

* bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (GH-21858)

Use generic '.. object::' to declare markers, rather than abusing
'..  c:function::' which fails on Sphinx 3.

(cherry picked from commit 43577c01a2ab49122db696e9eaec6cb31d11cc81)

* bpo-40204: Fix duplicates in the documentation (GH-21857)

Fix two Sphinx 3 issues:

Doc/c-api/buffer.rst:304: WARNING: Duplicate C declaration, also defined in 'c-api/buffer'.
Declaration is 'PyBUF_ND'.

Doc/c-api/unicode.rst:1603: WARNING: Duplicate C declaration, also defined in 'c-api/unicode'.
Declaration is 'PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)'.

(cherry picked from commit 46d10b1237c67ff8347f533eda6a5468d098f7eb)

* bpo-40204: Add :noindex: in the documentation (GH-21859)

Add :noindex: to duplicated documentation to fix "duplicate object
description" errors.

For example, fix this Sphinx 3 issue:

Doc/library/configparser.rst:1146: WARNING: duplicate object
description of configparser.ConfigParser.optionxform, other instance
in library/configparser, use :noindex: for one of them

(cherry picked from commit d3ded080482beae578faa704b13534a62d066f9f)

* bpo-40204, doc: Fix syntax of C variables (GH-21846)

For example, fix the following Sphinx 3 errors:

Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
  void \*obj
  -----^

Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
  PyObject*
  --------^

The modified documentation is compatible with Sphinx 2 and Sphinx 3.

(cherry picked from commit 474652fe9346382dbf793f20b671eb74668bebde)

* bpo-40204: Fix reference to terms in the doc (GH-21865)

Sphinx 3 requires to refer to terms with the exact case.

For example, fix the Sphinx 3 warning:

Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case
sensitive match.made a reference to loader instead.

(cherry picked from commit bb0b08540cc93e56f3f1bde1b39ce086d9e35fe1)

* bpo-40204: Fix duplicated productionlist names in the doc (GH-21900)

Sphinx 3 disallows having more than one productionlist markup with
the same name. Simply remove names in this case, since names are not
shown anyway. For example, fix the Sphinx 3 warning:

Doc/reference/introduction.rst:96: duplicate token description
of *:name, other instance in reference/expressions

(cherry picked from commit 1abeda80f760134b4233608e2c288790f955b95a)
(cherry picked from commit 8f88190af529543c84d5dc78f19abbfd73335cf4)

1 files changed, 11 insertions, 13 deletions

diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index 909deb5..f0081e4 100644
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -272,9 +272,7 @@ should instead read:
 Available static markers
 ------------------------
 
-.. I'm reusing the "c:function" type for markers
-
-.. c:function:: function__entry(str filename, str funcname, int lineno)
+.. object:: function__entry(str filename, str funcname, int lineno)
 
    This marker indicates that execution of a Python function has begun.
    It is only triggered for pure-Python (bytecode) functions.
@@ -290,7 +288,7 @@ Available static markers
 
        * ``$arg3`` : ``int`` line number
 
-.. c:function:: function__return(str filename, str funcname, int lineno)
+.. object:: function__return(str filename, str funcname, int lineno)
 
    This marker is the converse of :c:func:`function__entry`, and indicates that
    execution of a Python function has ended (either via ``return``, or via an
@@ -298,7 +296,7 @@ Available static markers
 
    The arguments are the same as for :c:func:`function__entry`
 
-.. c:function:: line(str filename, str funcname, int lineno)
+.. object:: line(str filename, str funcname, int lineno)
 
    This marker indicates a Python line is about to be executed.  It is
    the equivalent of line-by-line tracing with a Python profiler.  It is
@@ -306,24 +304,24 @@ Available static markers
 
    The arguments are the same as for :c:func:`function__entry`.
 
-.. c:function:: gc__start(int generation)
+.. object:: gc__start(int generation)
 
    Fires when the Python interpreter starts a garbage collection cycle.
    ``arg0`` is the generation to scan, like :func:`gc.collect()`.
 
-.. c:function:: gc__done(long collected)
+.. object:: gc__done(long collected)
 
    Fires when the Python interpreter finishes a garbage collection
    cycle. ``arg0`` is the number of collected objects.
 
-.. c:function:: import__find__load__start(str modulename)
+.. object:: import__find__load__start(str modulename)
 
    Fires before :mod:`importlib` attempts to find and load the module.
    ``arg0`` is the module name.
 
    .. versionadded:: 3.7
 
-.. c:function:: import__find__load__done(str modulename, int found)
+.. object:: import__find__load__done(str modulename, int found)
 
    Fires after :mod:`importlib`'s find_and_load function is called.
    ``arg0`` is the module name, ``arg1`` indicates if module was
@@ -332,7 +330,7 @@ Available static markers
    .. versionadded:: 3.7
 
 
-.. c:function:: audit(str event, void *tuple)
+.. object:: audit(str event, void *tuple)
 
    Fires when :func:`sys.audit` or :c:func:`PySys_Audit` is called.
    ``arg0`` is the event name as C string, ``arg1`` is a :c:type:`PyObject`
@@ -375,14 +373,14 @@ If this file is installed in SystemTap's tapset directory (e.g.
 ``/usr/share/systemtap/tapset``), then these additional probepoints become
 available:
 
-.. c:function:: python.function.entry(str filename, str funcname, int lineno, frameptr)
+.. object:: python.function.entry(str filename, str funcname, int lineno, frameptr)
 
    This probe point indicates that execution of a Python function has begun.
    It is only triggered for pure-Python (bytecode) functions.
 
-.. c:function:: python.function.return(str filename, str funcname, int lineno, frameptr)
+.. object:: python.function.return(str filename, str funcname, int lineno, frameptr)
 
-   This probe point is the converse of :c:func:`python.function.return`, and
+   This probe point is the converse of ``python.function.return``, and
    indicates that execution of a Python function has ended (either via
    ``return``, or via an exception).  It is only triggered for pure-Python
    (bytecode) functions.