[issue18758] Fix internal references in the documentation
New submission from Serhiy Storchaka: This is a meta issue for fixing broken references in the documentation. I will open a child issues for some groups of modules and finally provide a patch for rest files. ---------- assignee: docs@python components: Documentation messages: 195392 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Fix internal references in the documentation versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Fix internal references for concurrent modules, References to non-existant "StringIO" module _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Ezio Melotti added the comment: Note that not all the targets should be converted to links. They should be converted only if the link is useful, and usually redundant links are not necessary (e.g. if the same target is repeated several times in the same paragraph/section). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Fix internal doc references for logging package, Fix internal doc references for the xml package _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment: In such case perhaps links should be explicitly prohibited (with '!' mark). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Fix internal doc references for the email package _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Ezio Melotti added the comment: That's probably not worth it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- assignee: docs@python -> serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Georg Brandl added the comment: Definitely not. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Ezio Melotti added the comment: Serhiy, are you planning to work on more patches or can this be closed? ---------- type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment: Yes. I have 180 Kb patch which touches 107 files, and this is yet too large for one issue. I will continue split this patch for lesser issues. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in builtins documentation., Improve cross-references in pickle documentation. _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in tutorial _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in fcntl documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in C API _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in pickle documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in cgi documentation, Improve cross-references in shlex documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in curses howto _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in urllib documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- dependencies: +Improve cross-references in os documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment: And here is a patch with small changes which doesn't worth separated issue. ---------- keywords: +patch stage: -> patch review Added file: http://bugs.python.org/file32019/refs.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Georg Brandl added the comment: Looks good, except that buffer doesn't really correspond to bytearray. No memoryview involved there? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment: No. BytesWarning is related only to bytes and bytearray. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Georg Brandl added the comment: OK then -- so much the better. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment: Here is a patch to Sphinx which helped me to search dead internal references. Not all references were fixed by proposed patches. ---------- Added file: http://bugs.python.org/file32061/sphinx_warn_refs.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Georg Brandl added the comment: The -n (nitpicky) option to Sphinx should also report missing references. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment:
The -n (nitpicky) option to Sphinx should also report missing references.
Great. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Roundup Robot added the comment: New changeset fa7cfbec0d32 by Serhiy Storchaka in branch '2.7': Issue #18758: Fixed and improved cross-references. http://hg.python.org/cpython/rev/fa7cfbec0d32 New changeset 907da535ed9d by Serhiy Storchaka in branch '3.3': Issue #18758: Fixed and improved cross-references. http://hg.python.org/cpython/rev/907da535ed9d New changeset 261d9bf0cc2b by Serhiy Storchaka in branch 'default': Issue #18758: Fixed and improved cross-references. http://hg.python.org/cpython/rev/261d9bf0cc2b ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Serhiy Storchaka added the comment: Thank you Georg for all your reviews. Only patch for pickle left, and this is not trivial one. ---------- resolution: -> fixed stage: patch review -> committed/rejected _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
Georg Brandl added the comment: Thank you for all the effort you put into this! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue18758> _______________________________________
participants (4)
-
Ezio Melotti -
Georg Brandl
-
Roundup Robot
-
Serhiy Storchaka