Handle aliased functions and methods in generated documentation

src/sage/combinat/designs/database.py

@@ -5611,4 +5611,4 @@ def ca_41_2_6_6():
     LIST_OF_EDS=LIST_OF_EDS,
     LIST_OF_CA_CONSTRUCTIONS=LIST_OF_CA_CONSTRUCTIONS)
 del LIST_OF_OA_CONSTRUCTIONS, LIST_OF_MOLS_CONSTRUCTIONS, LIST_OF_VMT_VECTORS,LIST_OF_DF, LIST_OF_DM, LIST_OF_QDM, LIST_OF_EDS, LIST_OF_BIBD, LIST_OF_CA_CONSTRUCTIONS
-del PolynomialRing, ZZ, a,
+del PolynomialRing, ZZ, a, f,

src/sage/misc/sagedoc_conf.py

@@ -1,9 +1,16 @@
 r"""
 Sphinx configuration shared by sage.misc.sphinxify and sage_docbuild
+
+AUTHORS:
+
+- Matthias Koeppe, Kwankyu Lee (2022): initial version
+- Vincent Macri (2025-09-01): process_docstring_aliases
 """
 
 # ****************************************************************************
 #       Copyright (C) 2022 Matthias Koeppe <[email protected]>
+#                     2022 Kwankyu Lee <[email protected]>
+#                     2025 Vincent Macri <[email protected]>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -24,9 +31,47 @@ def process_docstring_aliases(app, what, name, obj, options, docstringlines):
     """
     Change the docstrings for aliases to point to the original object.
     """
-    basename = name.rpartition('.')[2]
-    if hasattr(obj, '__name__') and obj.__name__ != basename:
-        docstringlines[:] = ['See :obj:`%s`.' % name]
+
+    if what not in ('function', 'method'):
+        # Alias detection doesn't make sense for modules.
+        # Alias handling is implemented for classes in:
+        # src/sage_docbuild/ext/sage_autodoc.py
+
+        # Since sage_autodoc is supposed to be replaced (issue #30893)
+        # we implement function/method alias handling here rather than
+        # where class alias handling is implemented.
+        return
+
+    if not hasattr(obj, '__name__'):
+        # obj has no __name__
+        # This usually happens with factory functions, which should have their
+        # own docstring anyway.
+        return  # Skip alias detection if __name__ is not present
+
+    obj_name = name.rpartition('.')[2]  # Unqualified name
+    original_name = obj.__name__
+
+    if obj_name == original_name or original_name.startswith('_'):
+        # If obj_name == original_name this is not an alias.
+
+        # If original_name starts with '_' then this is a public alias
+        # of a private function/method and so we keep the docstring.
+        return None
+
+    if what == 'method':
+        docstringlines[:] = [f'alias of :meth:`{original_name}`.']
+        return
+
+    # We now have `what == 'function'`
+
+    if original_name != '<lambda>':
+        docstringlines[:] = [f'alias of :func:`{original_name}`.']
+        return
+
+    # If original_name == '<lambda>' then the function is
+    # a lambda expression, hence not an alias of something
+    # with its own docstring.
+    return
 
 
 def process_directives(app, what, name, obj, options, docstringlines):
@@ -164,4 +209,5 @@ def setup(app):
     app.connect('autodoc-process-docstring', process_dollars)
     app.connect('autodoc-process-docstring', process_inherited)
     app.connect('autodoc-process-docstring', skip_TESTS_block)
+
     app.add_transform(SagemathTransform)

src/sage_docbuild/conf.py

@@ -1078,6 +1078,7 @@ def setup(app):
     app.connect('autodoc-process-docstring', process_docstring_module_title)
     app.connect('autodoc-process-docstring', process_dollars)
     app.connect('autodoc-process-docstring', process_inherited)
+    app.connect('autodoc-process-docstring', process_docstring_aliases)
     if os.environ.get('SAGE_SKIP_TESTS_BLOCKS', False):
         app.connect('autodoc-process-docstring', skip_TESTS_block)
     app.connect('autodoc-skip-member', skip_member)