Attached patch reworks a bit the HTMLParser doc:
 - moved the basic example on the top and showed the output;
 - added a more complete parser with other examples;
 - fixed some factual errors;
 - added additional information for some methods;
 - added a couple of headers to divide the sections;
 - rephrased the text a bit to be more coherent and clear;
 - fixed a few links, typos, and terms;

I think the note about IE condcoms could be removed by the handle_comment doc, since it's already in the examples at the bottom.  A note in handle_data about the behavior with buffered input might be added in addition to the example at the bottom.

Didn’t review in detail but the plan LGTM.

In a subsequent commit, you could update the markup to use nested class/method directives.

Do you remember how to do it?

It’s all in the Documenting Python doc.

.. class:: HTMLParser()

   Blah blah.

   .. method:: feed(data)

      Do X and Y.

   The following attributes are supported:

   .. attribute:: pos

      etc.

Yes, but there's a section with the example in the middle now, so that doesn't work.  I was thinking about a way to tell sphinx "these are methods of the Foo class", without having them directly indented under the 'class' directive.

Just indent the example, or move it below!

New changeset 7052eb923fb8 by Ezio Melotti in branch '2.7':
#14020: improve HTMLParser documentation.
http://hg.python.org/cpython/rev/7052eb923fb8

New changeset 569566cbfd13 by Ezio Melotti in branch '3.2':
#14020: improve HTMLParser documentation.
http://hg.python.org/cpython/rev/569566cbfd13

New changeset 1850f45f6169 by Ezio Melotti in branch 'default':
#14020: merge with 3.2.
http://hg.python.org/cpython/rev/1850f45f6169