From 74bde2cb1378dbd40190e861e69e6f7102f68080 Mon Sep 17 00:00:00 2001 From: priyam0k <87162535+priyam0k@users.noreply.github.com> Date: Sun, 31 May 2026 01:18:07 +0530 Subject: [PATCH] docs: render API methods inline via custom autosummary templates (#847) Add custom autosummary templates (_templates/autosummary/{class,class_inherited,function}.rst) so API class pages document methods and properties inline instead of as a summary table linking to per-method stub pages. - Reference templates without the .rst extension in api.md; the prior ':template: class.rst' refs never resolved (Sphinx appends .rst, producing class.rst.rst) and silently fell back to the base template. - Set numpydoc_show_class_members=False and templates_path=['_templates'] so numpydoc no longer emits the duplicate members summary table. - Fix linkcode_resolve to unwrap property objects to their fget and guard inspect.getsourcefile/getsourcelines; documenting members inline exposed property objects that previously crashed the full jb build with a TypeError. --- docs/_config.yml | 2 ++ docs/_ext/linkcode.py | 20 ++++++++++++++++--- docs/_templates/autosummary/class.rst | 8 ++++++++ .../autosummary/class_inherited.rst | 9 +++++++++ docs/_templates/autosummary/function.rst | 5 +++++ docs/conf.py | 2 ++ docs/library/api.md | 16 +++++++-------- 7 files changed, 51 insertions(+), 11 deletions(-) create mode 100644 docs/_templates/autosummary/class.rst create mode 100644 docs/_templates/autosummary/class_inherited.rst create mode 100644 docs/_templates/autosummary/function.rst diff --git a/docs/_config.yml b/docs/_config.yml index 4dccd8ab..4f971481 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -43,6 +43,8 @@ sphinx: linkcode: _ext config: autosummary_generate: True + templates_path: ['_templates'] + numpydoc_show_class_members: False bibtex_reference_style: author_year parse: diff --git a/docs/_ext/linkcode.py b/docs/_ext/linkcode.py index 6ec36560..fe5fb8ec 100644 --- a/docs/_ext/linkcode.py +++ b/docs/_ext/linkcode.py @@ -53,11 +53,21 @@ def linkcode_resolve(domain: str, info: dict) -> str | None: for part in info["fullname"].split("."): obj: type = getattr(obj, part) + # Resolve properties to their underlying getter function. + if isinstance(obj, property): + obj = obj.fget + if obj is None: + return None + # Unwrap any decorators. obj: type = inspect.unwrap(obj) - # Get the path of the source file. - source_file: str = inspect.getsourcefile(obj) + # Get the path of the source file. Some objects (e.g. C-level callables or + # dynamically created members) are not introspectable; skip linking those. + try: + source_file: str = inspect.getsourcefile(obj) + except TypeError: + return None # If the source file cannot be found, return the URL pointing to a .py file named after the module. if source_file is None: @@ -65,7 +75,11 @@ def linkcode_resolve(domain: str, info: dict) -> str | None: return url_base + "%s.py" % filename # Extract the lines and locate the starting line position. - source_lines, start_line = inspect.getsourcelines(obj) + try: + source_lines, start_line = inspect.getsourcelines(obj) + except (TypeError, OSError): + filename: str = info["module"].replace(".", "/") + return url_base + "%s.py" % filename # Get the root path. root_path: str = os.path.abspath(os.path.join(cl.__file__, "..", "..")) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 00000000..3367eef4 --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,8 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/_templates/autosummary/class_inherited.rst b/docs/_templates/autosummary/class_inherited.rst new file mode 100644 index 00000000..e15788cd --- /dev/null +++ b/docs/_templates/autosummary/class_inherited.rst @@ -0,0 +1,9 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :undoc-members: + :inherited-members: + :show-inheritance: diff --git a/docs/_templates/autosummary/function.rst b/docs/_templates/autosummary/function.rst new file mode 100644 index 00000000..27ca987d --- /dev/null +++ b/docs/_templates/autosummary/function.rst @@ -0,0 +1,5 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autofunction:: {{ objname }} diff --git a/docs/conf.py b/docs/conf.py index 40e4f4a7..07167688 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,5 +40,7 @@ numfig = True pygments_style = 'sphinx' suppress_warnings = ['myst.domains'] +templates_path = ['_templates'] +numpydoc_show_class_members = False use_jupyterbook_latex = True use_multitoc_numbering = True diff --git a/docs/library/api.md b/docs/library/api.md index d0985fab..3f0aee87 100644 --- a/docs/library/api.md +++ b/docs/library/api.md @@ -20,7 +20,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class_inherited.rst + :template: class_inherited Triangle DevelopmentCorrelation @@ -43,7 +43,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class.rst + :template: class Development DevelopmentConstant @@ -72,7 +72,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class.rst + :template: class TailConstant TailCurve @@ -96,7 +96,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class.rst + :template: class Chainladder MackChainladder @@ -119,7 +119,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class.rst + :template: class BootstrapODPSample BerquistSherman @@ -140,7 +140,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class.rst + :template: class Pipeline VotingChainladder @@ -162,7 +162,7 @@ Functions .. autosummary:: :toctree: generated/ - :template: function.rst + :template: function load_sample read_pickle @@ -178,7 +178,7 @@ Classes .. autosummary:: :toctree: generated/ - :template: class.rst + :template: class PatsyFormula