Skip to content

Commit 1fd3a29

Browse files
committed
Docstring alias handling for function and methods
1 parent 4cdd703 commit 1fd3a29

File tree

3 files changed

+50
-7
lines changed

3 files changed

+50
-7
lines changed

src/sage/combinat/designs/database.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5611,4 +5611,4 @@ def ca_41_2_6_6():
56115611
LIST_OF_EDS=LIST_OF_EDS,
56125612
LIST_OF_CA_CONSTRUCTIONS=LIST_OF_CA_CONSTRUCTIONS)
56135613
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
5614-
del PolynomialRing, ZZ, a,
5614+
del PolynomialRing, ZZ, a, f,

src/sage/misc/sagedoc_conf.py

Lines changed: 48 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
r"""
22
Sphinx configuration shared by sage.misc.sphinxify and sage_docbuild
3+
4+
AUTHORS:
5+
6+
- Matthias Koeppe (2022): initial version
7+
- Vincent Macri (2025-09-01): process_docstring_aliases
38
"""
49

510
# ****************************************************************************
611
# Copyright (C) 2022 Matthias Koeppe <[email protected]>
12+
# 2025 Vincent Macri <[email protected]>
713
#
814
# This program is free software: you can redistribute it and/or modify
915
# it under the terms of the GNU General Public License as published by
@@ -21,12 +27,47 @@
2127

2228

2329
def process_docstring_aliases(app, what, name, obj, options, docstringlines):
24-
"""
25-
Change the docstrings for aliases to point to the original object.
26-
"""
27-
basename = name.rpartition('.')[2]
28-
if hasattr(obj, '__name__') and obj.__name__ != basename:
29-
docstringlines[:] = ['See :obj:`%s`.' % name]
30+
"""Change the docstrings for aliases to point to the original object."""
31+
32+
if what not in ('function', 'method'):
33+
# Alias detection doesn't make sense for modules.
34+
# Alias handling is implemented for classes in:
35+
# src/sage_docbuild/ext/sage_autodoc.py
36+
37+
# Since sage_autodoc is supposed to be replaced (issue #30893)
38+
# we implement function/method alias handling here rather than
39+
# where class alias handling is implemented.
40+
return
41+
42+
if not hasattr(obj, '__name__'):
43+
# obj has no __name__
44+
# This usually happens with factory functions, which should have their
45+
# own docstring anyway.
46+
return # Skip alias detection if __name__ is not present
47+
48+
obj_name = name.rpartition('.')[2] # Unqualified name
49+
original_name = obj.__name__
50+
51+
if obj_name == original_name or original_name.startswith('_'):
52+
# If obj_name == original_name this is not an alias.
53+
54+
# If original_name starts with '_' then this is a public alias
55+
# of a private function/method and so we keep the docstring.
56+
return None
57+
58+
if what == 'method':
59+
docstringlines[:] = [f'alias of :meth:`{original_name}`.']
60+
return
61+
62+
# elif what == 'function'
63+
64+
if original_name != '<lambda>':
65+
docstringlines[:] = [f'alias of :func:`{original_name}`.']
66+
return
67+
68+
# If original_name == '<lambda>' then the function is
69+
# a lambda expression, hence not an alias of something
70+
# with its own docstring.
3071

3172

3273
def process_directives(app, what, name, obj, options, docstringlines):
@@ -164,4 +205,5 @@ def setup(app):
164205
app.connect('autodoc-process-docstring', process_dollars)
165206
app.connect('autodoc-process-docstring', process_inherited)
166207
app.connect('autodoc-process-docstring', skip_TESTS_block)
208+
167209
app.add_transform(SagemathTransform)

src/sage_docbuild/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1078,6 +1078,7 @@ def setup(app):
10781078
app.connect('autodoc-process-docstring', process_docstring_module_title)
10791079
app.connect('autodoc-process-docstring', process_dollars)
10801080
app.connect('autodoc-process-docstring', process_inherited)
1081+
app.connect('autodoc-process-docstring', process_docstring_aliases)
10811082
if os.environ.get('SAGE_SKIP_TESTS_BLOCKS', False):
10821083
app.connect('autodoc-process-docstring', skip_TESTS_block)
10831084
app.connect('autodoc-skip-member', skip_member)

0 commit comments

Comments
 (0)