Move all bytes/bytearray/int/float/complex documentation to Built-in Types

[andresdelfino]

BPO	34116
Nosy	@rhettinger, @andresdelfino
PRs	bpo-34116: Move all bytes/bytearray/int/float/complex documentation to Built-in Types #8286

^{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 2018-07-16.09:53:26.927>
created_at = <Date 2018-07-15.00:07:30.079>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Move all bytes/bytearray/int/float/complex documentation to Built-in Types'
updated_at = <Date 2018-07-16.09:53:26.925>
user = 'https://github.com/andresdelfino'

bugs.python.org fields:

activity = <Date 2018-07-16.09:53:26.925>
actor = 'rhettinger'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-07-16.09:53:26.927>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2018-07-15.00:07:30.079>
creator = 'adelfino'
dependencies = []
files = []
hgrepos = []
issue_num = 34116
keywords = ['patch']
message_count = 3.0
messages = ['321667', '321669', '321728']
nosy_count = 3.0
nosy_names = ['rhettinger', 'docs@python', 'adelfino']
pr_nums = ['8286']
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue34116'
versions = ['Python 2.7', 'Python 3.6', 'Python 3.7', 'Python 3.8']

[andresdelfino]

Right now, bytearray, bytes, complex, float and int documentation is splitted into stdtypes.rst and functions.rst. I think stdtypes.rst should be the only source with all documentation, and functions.rst should just point out to stdtypes.rst. This would make it easier to get the complete picture of a given type without having to jump between pages. This is how the documentation of dict, frozenset, list, memoryview, range, set, str and tuple works.

I believe bool() is more useful in functions.rst, as it's really short.

[andresdelfino]

See talk at: https://python.zulipchat.com/#narrow/stream/116633-documentation/subject/Gather.20all.20type.20documentation.20in.20stdtypes

[rhettinger]

I disagree that this would be an improvement. The current organization has worked well for us. In particular, some of the these types sometimes used like functions that produce a type (this is where the builtin functions docs do a good job). In the stdtypes docs, we go into detail about what the types do and have them grouped in a way that can be compared and contrasted.

As a Python instructor, I ask newcomers to read the built-in functions section because it tells them a lot of what they need to know to get up and running with the language (indeed, that is why these are all builitins rather than relegated to modules). The stdtypes section is more voluminous and rarely read start to finish (mostly just used as a reference).