Skip to content

DOCS: Render API methods inline via custom autosummary templates (#847)#885

Merged
henrydingliu merged 1 commit into
casact:experimentalfrom
priyam0k:docs/847-api-doc-templates
May 30, 2026
Merged

DOCS: Render API methods inline via custom autosummary templates (#847)#885
henrydingliu merged 1 commit into
casact:experimentalfrom
priyam0k:docs/847-api-doc-templates

Conversation

@priyam0k
Copy link
Copy Markdown
Contributor

@priyam0k priyam0k commented May 30, 2026

Summary of Changes

  • Adds custom sphinx.ext.autosummary templates under docs/_templates/autosummary/: class.rst, class_inherited.rst, function.rst.
  • API class pages now list methods and properties inline instead of a summary table that links to a separate page per method.
  • Fixes the :template: names in docs/library/api.md to drop .rst (:template: class.rst:template: class).
  • Sets numpydoc_show_class_members = False and templates_path = ['_templates'] in docs/_config.yml (and the generated docs/conf.py).
  • Guards docs/_ext/linkcode.py against property objects so inline members don't crash the build.

Three issues fixed along the way:

  1. :template: class.rst never worked. Sphinx appends .rst, so it looked for autosummary/class.rst.rst and fell back to the base template. Names now omit the extension.
  2. numpydoc duplicate table. numpydoc_show_class_members = False stops numpydoc emitting its own members table next to the inline members.
  3. linkcode_resolve crash. Inline members pass property objects to the resolver, where inspect.getsourcefile(property) raises TypeError and aborts jb build. Fixed by unwrapping properties to fget and guarding getsourcefile / getsourcelines.

Related GitHub Issue(s)

Additional Context for Reviewers

  • conf.py is regenerated from _config.yml by Jupyter Book; both updated to stay in sync.

  • jb build . succeeds (warnings all pre-existing). HTML spot checks:

    Page Inline methods Inline properties numpydoc table
    Development (class) 3 0 none
    Triangle (class_inherited) 64 24 none
    load_sample (function) function block

One thing to decide: with :inherited-members: on, Triangle shows 64 methods and 24 properties, including sklearn ones it inherits like get_params, set_output, set_fit_request, get_metadata_routing. Do you want all of those shown, or should I hide the sklearn ones (or just drop inherited members entirely)? Let me know which you prefer and I'll adjust.

  • Verified documentation changes locally with jb build . (HTML builder).

…act#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.
@codecov
Copy link
Copy Markdown

codecov Bot commented May 30, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.04%. Comparing base (4ce0141) to head (74bde2c).
⚠️ Report is 1 commits behind head on experimental.

Additional details and impacted files
@@              Coverage Diff              @@
##           experimental     #885   +/-   ##
=============================================
  Coverage         87.04%   87.04%           
=============================================
  Files                86       86           
  Lines              4986     4986           
  Branches            646      646           
=============================================
  Hits               4340     4340           
  Misses              456      456           
  Partials            190      190           
Flag Coverage Δ
unittests 87.04% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@priyam0k priyam0k marked this pull request as ready for review May 30, 2026 20:24
@henrydingliu henrydingliu merged commit 77c75aa into casact:experimental May 30, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants