| msg325577 - (view) |
Author: Yury Selivanov (yselivanov) *  |
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) * |
Date: 2018-09-17 21:14 |
| Please refer to the attached screenshots to see the difference. |
|
|
| msg325580 - (view) |
Author: Julien Palard (mdk) * |
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) * |
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) * |
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. |
|
|
