|
1 | 1 | r"""
|
2 | 2 | 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 |
3 | 8 | """
|
4 | 9 |
|
5 | 10 | # ****************************************************************************
|
6 | 11 | # Copyright (C) 2022 Matthias Koeppe <[email protected]>
|
| 12 | +# 2025 Vincent Macri <[email protected]> |
7 | 13 | #
|
8 | 14 | # This program is free software: you can redistribute it and/or modify
|
9 | 15 | # it under the terms of the GNU General Public License as published by
|
|
21 | 27 |
|
22 | 28 |
|
23 | 29 | 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. |
30 | 71 |
|
31 | 72 |
|
32 | 73 | def process_directives(app, what, name, obj, options, docstringlines):
|
@@ -164,4 +205,5 @@ def setup(app):
|
164 | 205 | app.connect('autodoc-process-docstring', process_dollars)
|
165 | 206 | app.connect('autodoc-process-docstring', process_inherited)
|
166 | 207 | app.connect('autodoc-process-docstring', skip_TESTS_block)
|
| 208 | + |
167 | 209 | app.add_transform(SagemathTransform)
|
0 commit comments