It might be helpful to make a document about linking, together with some examples of right and wrong :)

@charris Any suggestions on where to add it? Where you thinking to the numpy site, or just the POSSEE project?

The Sphinx docs has a referencing page that is quite helpful. It's general though and numpy's configuration file enables some things that aren't on that page. It does explain how the ~ works. The numpydocs instructions related to internal links are quite sparse. Maybe that would be a good place to add the examples.

I wrote up a short description for the POSSEE project that has a few examples I could add to the numpydocs page (I added them below). Thoughts?

``default_rng`` #appears as monospace. Should be avoided for numpy functions
`default_rng` #creates internal link to default_rng, of which the only one is numpy.random.default_rng
`~default_rng` #same as above, the tilde isn't needed
`numpy.random.default_rng` #creates internal link to numpy.random.default_rng
`~numpy.random.default_rng` #creates internal link to numpy.random.default_rng, but the link text is default_rng

I've seen other examples in the docs that include a ~ along with various other things (for example ~.default_rng, ~random.default_rng). Maybe the inconsistency is fine and the best approach is to just leave the longer versions that work. The hard part comes into play when a new method is created such as integers which requires ~Generator.integers to appropriately link it, or another such as random for which there are many options and you must include the tilde to get ~Generator.integers.

Thanks Ben. Because you have verified the docs, I don't have a problem putting this in.

As to where to put the information on linking, numpydoc is probably the best spot. Is it safe to say ~numpy.random.default_rng, with and without the tilde, will always work, but that there are more concise ways to get the same result? I'm thinking "when in doubt ...".