Improve "Extending Python with C or C++" docs

[erlend-aasland]

Quoting Petr in issue gh-93078:

Anyway, the more important thing to do here is converting the tutorial. That will, in my opinion, make the new way official :)
But I don't want to do that until PEP 687 is accepted, and more PEP 630 open issues are solved. (FWIW: Metaclasses and Per-class scope look like they could go in anearly 3.12 alpha, Type checking should hopefully go in 3.12 as well, and lossless conversion isn't blocking for me.)

But yes, all that is out of scope of this PR.

Originally posted by @encukou in #93078 (comment)

[encukou]

cc @ericsnowcurrently

[elmbeech]

Hello!
I have just written my first extended python module. Thank you for the documentation, it was a good help! A minor thing I found in the example code, that I think, should be different.
Under 1. Extending Python with C or C++ : 1.1. A Simple Example , 1.2. Intermezzo: Errors and Exceptions, and 1.3. Back to the Example.

• https://docs.python.org/3/extending/extending.html

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return PyLong_FromLong(sts);
}

Should return NULL; not better be return Py_None;?

[erlend-aasland]

should return NULL; not better be return Py_None;?

Take a look at the immediately following section (1.2 Intermezzo: Errors and Exceptions), where this is explained.

[elmbeech]

thank you! and sorry if this is just because I not understood everything.