unittest.mock has wrong heading levels

[pitrou]

BPO	17109
Nosy	@birkenfeld, @pitrou, @ezio-melotti, @voidspace, @cjerdonek

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2013-02-03.10:47:34.017>
created_at = <Date 2013-02-02.23:31:55.993>
labels = ['type-bug', 'library', 'docs']
title = 'unittest.mock has wrong heading levels'
updated_at = <Date 2013-02-22.02:20:37.727>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2013-02-22.02:20:37.727>
actor = 'chris.jerdonek'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-02-03.10:47:34.017>
closer = 'python-dev'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2013-02-02.23:31:55.993>
creator = 'pitrou'
dependencies = []
files = []
hgrepos = []
issue_num = 17109
keywords = []
message_count = 11.0
messages = ['181231', '181257', '181258', '181265', '181291', '181292', '181294', '181296', '181302', '181303', '182622']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'pitrou', 'ezio.melotti', 'michael.foord', 'chris.jerdonek', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue17109'
versions = ['Python 3.3', 'Python 3.4']

[pitrou]

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)

[python-dev]

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

[pitrou]

unittest.mock-examples.rst also needs fixing.

[python-dev]

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

[cjerdonek]

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

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

[cjerdonek]

Never mind :)

[cjerdonek]

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

[pitrou]

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.

[birkenfeld]

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

[cjerdonek]

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."

[cjerdonek]

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

I created bpo-17270 for this.