Skip to content

Comments

Fix Sphinx documentation build warnings#454

Closed
xiki-tempula wants to merge 3 commits intoalchemistry:masterfrom
xiki-tempula:feat_docs
Closed

Fix Sphinx documentation build warnings#454
xiki-tempula wants to merge 3 commits intoalchemistry:masterfrom
xiki-tempula:feat_docs

Conversation

@xiki-tempula
Copy link
Collaborator

Summary

  • Resolve all Sphinx build warnings (reduced from 104 to 0 code-related warnings) by fixing duplicate object descriptions, invalid RST markup, inconsistent docstring indentation, and suppressing unresolvable cross-references from inherited scikit-learn docstrings.
  • No documentation content is changed — all fixes are structural (Sphinx directives, indentation normalization, label deduplication).

Changes

Duplicate object descriptions from automodule + explicit directives:
Added :no-members: to automodule directives in files that also have explicit autofunction/autoclass directives below. The autodoc_default_options in conf.py sets "members": True globally, which caused automodule to auto-document all members — duplicating the explicit directives that follow.

  • parsing/alchemlyb.parsing.{amber,gmx,gomc,lammps,namd,util}.rst
  • postprocessors/alchemlyb.postprocessors.units.rst
  • preprocessing/alchemlyb.preprocessing.subsampling.rst
  • workflows/alchemlyb.workflows.base.rst

Duplicate object descriptions from autosummary + autoclass:
Added :no-index: to autoclass directives in individual API pages. The autosummary tables in parent pages already register these classes in Sphinx's index; the detailed API pages now render the full documentation without creating duplicate index entries.

  • estimators/alchemlyb.estimators.{BAR,MBAR,TI,TI_GQ}.rst
  • workflows/alchemlyb.workflows.{ABFE,base}.rst
  • convergence/alchemlyb.convergence.convergence.rst

RST / docstring fixes:

  • parsing/alchemlyb.parsing.lammps.rst: Fixed title underline length (was 1 char too short)
  • estimators/alchemlyb.estimators.TI.rst: Renamed label estimators_TI to estimators_TI_api to avoid collision with the same label in estimators-ti.rst
  • src/alchemlyb/parsing/namd.py: Replaced invalid :param:fep_filesrole with fep_files ``
  • src/alchemlyb/visualisation/convergence.py: Normalized mixed 5-space / 4-space docstring indentation to consistent 4-space for plot_convergence and plot_block_average, fixing "Unexpected section title" errors

Suppress unresolvable sklearn warnings:

  • docs/conf.py: Added suppress_warnings = ["ref.ref", "ref.term"] to silence warnings from inherited scikit-learn docstrings that reference internal sklearn labels (metadata_routing) and glossary terms (meta-estimator) we cannot resolve.

Test plan

  • make clean html in docs/ produces 0 code-related warnings (only 6 SSL/network warnings from intersphinx on local builds, which do not appear on CI/ReadTheDocs)

@codecov
Copy link

codecov bot commented Feb 11, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.01%. Comparing base (220141f) to head (fed4704).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #454   +/-   ##
=======================================
  Coverage   99.01%   99.01%           
=======================================
  Files          29       29           
  Lines        2446     2447    +1     
  Branches      464      464           
=======================================
+ Hits         2422     2423    +1     
  Misses          2        2           
  Partials       22       22           

☔ 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.

Copy link
Member

@orbeckst orbeckst left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, yolo!

@xiki-tempula
Copy link
Collaborator Author

Annoying, this break the hyperlink. I guess if not broken, don't fix it.

@xiki-tempula xiki-tempula deleted the feat_docs branch February 11, 2026 19:13
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