If you look at http://docs.python.org/dev/library/development.html, you'll see the following outline (stripped for brevity):
     
26.4. unittest.mock — mock object library

    26.4.1. Quick Guide
    26.4.2. The Mock Class

26.5. The patchers

26.6. MagicMock and magic method support

26.7. Helpers

26.8. unittest.mock — getting started

26.9. Further Examples

26.10. 2to3 - Automated Python 2 to 3 code translation


Instead, it should be:

26.4. unittest.mock — mock object library

    26.4.1. Quick Guide
    26.4.2. The Mock Class
    26.4.3. The patchers
    26.4.4. MagicMock and magic method support
    26.4.5. Helpers

26.5. unittest.mock — getting started

    26.5.1. Further Examples

26.6. 2to3 - Automated Python 2 to 3 code translation


(I'm also not sure the reference document should come before the getting started document)

New changeset 72aee7ee2299 by Georg Brandl in branch '3.3':
Closes #17109: fix heading levels in mock doc.
http://hg.python.org/cpython/rev/72aee7ee2299

unittest.mock-examples.rst also needs fixing.

New changeset 9040b3714207 by Georg Brandl in branch '3.3':
#17109: fix headings in mock example doc.
http://hg.python.org/cpython/rev/9040b3714207

How does the "+" level relate to the convention described here?

http://docs.python.org/devguide/documenting.html#sections

Never mind :)

I see why I was confused.  The ~'s are different from -'s.  The tilde level isn't listed in our devguide conventions.

> I see why I was confused.  The ~'s are different from -'s.  The tilde
> level isn't listed in our devguide conventions.

I think the conventions are just conventions, and docutils / sphinx
don't enforce any order. I may be wrong though.

Antoine is right.  It's probably ok to remove that suggestion completely.

I think the guidance is still helpful.  I have referred to it often.  It can just be changed to being a suggestion as opposed to "the convention that we use."

> It can just be changed to being a suggestion as opposed to "the convention that we use."

I created issue 17270 for this.