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

I'm already attempting something similar over at https://bugs.python.org/issue45840 (though that issue is for one specific piece of documentation). See also my attached PR, and the comments on it :)

It is a good idea in general. Please go ahead, I am sure that the PR will be accepted.

But keep in mind that not always additional links make the documentation better. The rule of tumb is to not add multiple links to the same entity in one paragraph. In many cases the second and the following references are made non-links intentionally. There is also not much benefit of making a link to itself (if the single-paragraph description of the function contains a reference to that function).

Thanks for the warning about double link. I agree with you.
I guess it's another reason why it would be non trivial to automate here.

I am generally in favor of adding more links.  PR-29633, covering one doc file, has more than enough changes for one PR.  Please read the original patch, the comments, and the subsequent changes.  I plan to do the same.