[docs] Improve C-API doc for PyTypeObject (issue 17045)

[ericsnowcurrently at gmail.com]

Thanks for the review, Ezio.  This really helps.  This page is packed
with information and I'm just hoping to distill some of the key
information here.  I'll take all the help I can get to get the markup
right and stay consistent with the docs as a whole, so thanks!


http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst
File Doc/c-api/typeobj.rst (right):

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode29
Doc/c-api/typeobj.rst:29: | :c:member:`tp_name <PyTypeObject.tp_name>`  
                  |     | char *                 |
On 2013/01/27 01:30:46, ezio.melotti wrote:
> You can use :c:member:`~PyTypeObject.tp_name` instead.

Good tip.

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode30
Doc/c-api/typeobj.rst:30:
+----------------------------------------------------------------+-----+------------------------+
On 2013/01/27 01:30:46, ezio.melotti wrote:
> Unless you want to rewrap to 80 chars and need to have more than one
line in the
> same cell, you can use the simpler syntax for tables, and get rid of
all the "|"
> lines (use a space to separate columns) and the "-" lines between rows
(you have
> to keep the ones around the header though).

I was going to do that, but was unsure of making it work with spaces in
a single cell.  Can you simply quote the cell contents or something?

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode123
Doc/c-api/typeobj.rst:123: Names in square brackets are for internal use
only.
On 2013/01/27 01:30:46, ezio.melotti wrote:
> This is usually done via notes that are then listed at the end of the
table.

Good point.

> In
> this specific case it could be even better to move the
deprecated/internal
> methods in one or two separate tables/lists.

For a quick reference, as I hope the table will serve, I figured it
would be good to have some visual indicator right in the table. 
However, it could just as easily be an extra column or two.  If you
think that's not worth it, I'm open to what you are suggesting, pushing
that info off into a separate section that need not be very big.

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode125
Doc/c-api/typeobj.rst:125: Inh:
On 2013/01/27 01:30:46, ezio.melotti wrote:
> This should be expanded a bit to clarify that it refers to the column
and what
> it means.

Agreed.

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode131
Doc/c-api/typeobj.rst:131: ? - it's complicated; see the slot's
description.
On 2013/01/27 01:30:46, ezio.melotti wrote:
> This could be done with notes as well.

Will do.

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode166
Doc/c-api/typeobj.rst:166: **Inheritance:**
On 2013/01/27 01:30:46, ezio.melotti wrote:
> This could be on the same line.
> I also wonder if there's a better way to mark this.  The markup you
are used is
> not used anywhere else in the docs AFAIK, and it might result a bit
inconsistent
> with the rest.

I'm totally open to suggestions here.  I wanted to have a uniform marker
for inheritance (and default) in the doc for each type slot -- one that
visually stands out, but not drastically.  However, the marker doesn't
need to be a reference of any kind.  Using a bold word was the simplest
thing I could think of.

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode384
Doc/c-api/typeobj.rst:384: Group: :attr:`tp_getattr`,
:attr:`tp_getattro`
On 2013/01/27 01:30:46, ezio.melotti wrote:
> Mayne you can use a double signature instead of this (assuming that it
makes
> sense to do so).

I wasn't thinking of this as more than plain text, but only because I
didn't see it as more than a simple marker of inheritance groups.  I'm
fine with more if you have something in mind.

As you've seen, I haven't spent much time editing the docs, so my ReST
is pretty basic and my knowledge of how we do it in the docs is really
limited.  So I'm grateful for this feedback.  :)

http://bugs.python.org/review/17045/diff/7222/Doc/c-api/typeobj.rst#newcode558
Doc/c-api/typeobj.rst:558: This field does not have a default.
On 2013/01/27 01:30:46, ezio.melotti wrote:
> Instead of keep repeating it, you could add at the top a line that
says
> something like "if no default it's specified the field has no
default".

Good idea.

http://bugs.python.org/review/17045/