New submission from Arthur Milchior <art...@milchior.fr>: I would like to work on this documentation improvement. Before spending time on it, I would like to know whether it would be accepted in principle and whether the way I would intend to improve the documentation would be accepted.
# Problem: In a lot of part of the documentation, the text refers to a method, function, built-in, variable, member defined somewhere else in the doc, but does not link to it (I'll call it "the defined thing" in the remaining of this BPO). ## Example As an example, in https://docs.python.org/3.10/library/imp.html#imp.reload , you'll get link to import from, but no link on __name__. Admittedly, it's probably not a big deal by itself, and I would not have opened a bug report only for this one. But I'm convinced that there are sufficiently many missing links that a PR that would solve add a lot of them would improve the day to day use of the documentation in a small way for a lot of users. This example seems interesting to me because it also shows that creating the links can not be 100% automated (even if most of it can). Indeed, __name__ is a property of modules, but it is also a property of class, function, method, descriptor and generator instances. The former is defined in https://docs.python.org/3.10/library/types.html?highlight=__name__#types.ModuleType.__name__ while the latter is defined in https://docs.python.org/3.10/library/stdtypes.html?highlight=__name__#definition.__name__ . Hence, a commit dealing with __name__ need to check that the correct reference is used each time. I got the idea from a change requested by Terry J Reedy on another of my documentation PR a few days ago: https://github.com/python/cpython/pull/29183#pullrequestreview-816414072 and I believe this should be more systematic. # How I'll solve this issue ## Ensuring the PR is easy to review For each defined thing, I'll create a commit that simply add links to this refered thing. In the example I gave, it will transform ``__name__`` to :meth:`__name__`. That means that each commit will be very easy to review (even if it will be boring). Even better, any diff tools can show that there are no other difference than the one I claim to make. ### One downside The downside is that it requires that I do not change the place where line break occurs (otherwise, git default diff tool will show a lot of difference). this mean that some lines will grow larger than 80 characters. In this case, I believe that this is a cost worth paying because: * there are already a lot of lines with more than 80 characters in the documentation, * reformating each paragraph will makes the reviewer work extremely hard, for virtually no benefits * if required, a last commit can reformat all paragraphs at the end. ## How I'll find missing references I will NOT find all missing references. I do not believe it is a realistic goal. My goal here is to improve the documentation, I don't care if it is not perfect here. What I do is that I search for lines containing matching the regexp `\`\.{2,}\`\`; they are generally, but not always, code that should be reference. For each missing reference, I'll use search and replace in the documentation codebase to replace the code by the link, I'll compile and check that the link works. ## Future work I believe ideally a linter should warn if a single word betwen `` and `` could potentially be a reference. This seems harder work to be honest, I don't know how I'd start it. And it seems useless while so many missing references are in the codebase. # Conclusion My questions are thus: * If I were to make such a PR, would it be accepted * is there any feedback, improvement one would suggest that may improve the result or save time ---------- assignee: docs@python components: Documentation messages: 407242 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: Many method, function, built-in... are not clickable and should be type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue45922> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
