To quote a great summary:

I think a developer docs page on how to do the links in notebooks is a good idea, since they really improve the documentation but are annoying to create! The learning curve is steep since you have to commit and wait for CI to run to get feedback on whether you're doing it correctly. For the record, here are three examples that finally worked:

For a function

[rot_a_to_b()]: ../api/plasmapy.formulary.mathematics.rot_a_to_b.rst#plasmapy.formulary.mathematics.rot_a_to_b

For a class

[SyntheticProtronRadiography]: ../api/plasmapy.diagnostics.proton_radiography.SyntheticProtonRadiograph.rst#plasmapy.diagnostics.proton_radiography.SyntheticProtonRadiograph

For a method of a class

[create_particles()]: 
../api/plasmapy.diagnostics.proton_radiography.SyntheticProtonRadiograph.rst#plasmapy.diagnostics.proton_radiography.SyntheticProtonRadiograph.create_particles

For an external website

[np.random.choice()]: https://numpy.org/doc/stable/reference/random/generated/numpy.random.choice.html

It would be worth explaining where the api/ files are created. These paths are relative to the main notebooks directory: if the notebook is in a sub folder (eg. cartesian_grids.ipynb which is in notebooks/plasma/) an additional ../ is required to get back to the api/ directory.

Originally posted by @pheuer in #1054 (comment)