This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: docs: disable numbered sections for stdlib in html
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Oliver Too Eh?, docs@python, ezio.melotti, mdk, miss-islington, willingc, yselivanov
Priority: normal Keywords: patch

Created on 2018-09-17 21:13 by yselivanov, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
now_2.png yselivanov, 2018-09-17 21:13
now_1.png yselivanov, 2018-09-17 21:14
after_1.png yselivanov, 2018-09-17 21:14
after_2.png yselivanov, 2018-09-17 21:14
Pull Requests
URL Status Linked Edit
PR 9370 merged yselivanov, 2018-09-17 21:15
PR 9375 merged miss-islington, 2018-09-17 22:12
Messages (7)
msg325577 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2018-09-17 21:13
I'd like to remove the ":numbered:" option from Doc/library/index.rst TOC.  Most standard library modules don't have extensive documentation, but some, for example asyncio, have.  For such modules, numbering makes title to contain too much noise.  Sphinx does not allow to opt-out from sections numbering if it's enabled on the top level.
msg325578 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2018-09-17 21:14
Please refer to the attached screenshots to see the difference.
msg325580 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-09-17 21:28
In one hand, I already spotted students exchanging paragraphs numbers, when both have the same page open but one want to point a specific paragraph to the other, it goes like "humm that thing is docuemtented in paragraph 3.17.3.12".

Don't mis-read me, they don't *know* the paragraph number, they read it because it's on their screen at the moment they use it, to temporarily exchange a specific location on the page.

On the other hand the numbering is inconsistent between versions, and I also seen students replying to the first one, it goes like: "oooh got it, it's not 3.17.3.12 but 3.17.3.16 in my version" (Obviously I'm make up numbers, too).

Soo... I'm +1 for this change.
msg325587 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2018-09-17 22:12
New changeset c62ab2862db2382808bb2228760eebdda3f608bd by Yury Selivanov in branch 'master':
bpo-34717: Stop numbering stdlib titles/sections in the docs (GH-9370)
https://github.com/python/cpython/commit/c62ab2862db2382808bb2228760eebdda3f608bd
msg325589 - (view) Author: Yury Selivanov (yselivanov) * (Python committer) Date: 2018-09-17 22:16
Thanks to Julien and Carol for reviews and sharing the opinion!  I'm closing this issue now.

In case someone needs the numbering to be re-enabled for some reason we can re-open this issue and discuss the best approach how to make that happen, while making sure that documentation for modules like asyncio is easy to browse and read.
msg325593 - (view) Author: miss-islington (miss-islington) Date: 2018-09-17 22:42
New changeset c63d81b3feaa008a6be4c7c83c324174e8d95c24 by Miss Islington (bot) in branch '3.7':
bpo-34717: Stop numbering stdlib titles/sections in the docs (GH-9370)
https://github.com/python/cpython/commit/c63d81b3feaa008a6be4c7c83c324174e8d95c24
msg340932 - (view) Author: Oliver Too, Eh? (Oliver Too Eh?) Date: 2019-04-26 16:32
As someone who is only now making the transition from Python 2 to Python 3, losing the numbering in the documentation on the Python Standard Library slows down my navigation when looking through the high-level contents.  

Given that the position of sections hasn't drifted much between versions, being able to treat the sections like chapters of a book affords faster access when I can quickly identify my position in the page without having to look at the scrollbar, provided my operating system even displays one when I am not actively scrolling.  Knowing that there are roughly 40 top-level sections in the library means I can find something I know to be in the middle much more quickly from its number (plus or minus version drift) and those of its local surroundings than by its overall position in the page.  Moreover, losing this feature can only be mitigated by search or "find in page" provided I remember modules and their contents by name, correctly spelled.

I appreciate the overall cleaner appearance as sections become heavily nested that is addressed by this enhancement.  I do however respectfully disagree with the choice of doing this at the expense of top level ordering.
History
Date User Action Args
2022-04-11 14:59:06adminsetgithub: 78898
2019-04-26 16:32:25Oliver Too Eh?setnosy: + Oliver Too Eh?
messages: + msg340932
2019-04-26 11:06:49xtreaklinkissue36727 superseder
2018-09-17 22:42:13miss-islingtonsetnosy: + miss-islington
messages: + msg325593
2018-09-17 22:16:28yselivanovsetversions: + Python 3.7, Python 3.8
2018-09-17 22:16:13yselivanovsetstatus: open -> closed
resolution: fixed
messages: + msg325589

stage: patch review -> resolved
2018-09-17 22:12:34miss-islingtonsetstage: patch review
pull_requests: + pull_request8799
2018-09-17 22:12:24yselivanovsetmessages: + msg325587
2018-09-17 21:28:18mdksetmessages: + msg325580
2018-09-17 21:16:23yselivanovsetnosy: + mdk
2018-09-17 21:16:06yselivanovsetnosy: + willingc, - mdk
stage: patch review -> (no value)
2018-09-17 21:15:53yselivanovsetkeywords: + patch
stage: patch review
pull_requests: + pull_request8793
2018-09-17 21:15:06ned.deilysetnosy: + mdk
2018-09-17 21:14:47yselivanovsetnosy: + ezio.melotti
2018-09-17 21:14:40yselivanovsetmessages: + msg325578
2018-09-17 21:14:25yselivanovsetfiles: + after_2.png
2018-09-17 21:14:20yselivanovsetfiles: + after_1.png
2018-09-17 21:14:09yselivanovsetfiles: + now_1.png
2018-09-17 21:13:57yselivanovcreate