DOC: Explain leading dot in object references

timhoffm · timhoffm · commit 92b39328e364 · 2024-03-18T22:08:39.000+01:00
diff --git a/doc/devel/document.rst b/doc/devel/document.rst
@@ -317,7 +317,10 @@ target is unambiguous you can simply leave them out:
 
   `.LineCollection`
 
-and the link still works: `.LineCollection`.
+and the link still works: `.LineCollection`. Note that you should typically include
+the leading dot, otherwise Sphinx will try to resolve the object only in the current
+module. See also the explanation at `Sphinx: Cross-referencing Python objects
+<https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects>`_.
 
 If there are multiple code elements with the same name (e.g. ``plot()`` is a
 method in multiple classes), you'll have to extend the definition:
