Fix Sphinx documentation build warnings

docs/conf.py

@@ -224,6 +224,10 @@
     ("py:class", "typing.Optional"),
 ]
 
+# Suppress warnings from inherited sklearn docstrings that reference
+# sklearn-internal labels and glossary terms we cannot resolve.
+suppress_warnings = ["ref.ref", "ref.term"]
+
 # Add any custom static files (CSS, JS, etc.)
 # html_static_path = ["_static"]
 

docs/convergence/alchemlyb.convergence.convergence.rst

@@ -28,5 +28,6 @@ All convergence functions are located in the :mod:`alchemlyb.convergence.converg
 
 .. automodule:: alchemlyb.convergence.convergence
    :members:
+   :no-index:
    :show-inheritance:
 

docs/estimators/alchemlyb.estimators.BAR.rst

@@ -13,3 +13,4 @@ API Reference
 .. autoclass:: alchemlyb.estimators.BAR
     :members:
     :inherited-members:
+    :no-index:

docs/estimators/alchemlyb.estimators.MBAR.rst

@@ -11,4 +11,5 @@ API Reference
 .. autoclass:: alchemlyb.estimators.MBAR
     :members:
     :inherited-members:
+    :no-index:
 

docs/estimators/alchemlyb.estimators.TI.rst

@@ -1,4 +1,4 @@
-.. _estimatators_TI:
+.. _estimators_TI_api:
 
 TI
 ==
@@ -9,3 +9,4 @@ API Reference
 .. autoclass:: alchemlyb.estimators.TI
     :members:
     :inherited-members:
+    :no-index:

docs/estimators/alchemlyb.estimators.TI_GQ.rst

@@ -1,9 +1,9 @@
-.. _estimatators_TI_GQ:
+.. _estimators_TI_GQ:
 
 TI_GQ
 =====
 The :class:`~alchemlyb.estimators.TI_GQ` estimator is an implementation of `thermodynamic integration <https://en.wikipedia.org/wiki/Thermodynamic_integration>`_ that uses the `gaussian quadrature <https://en.wikipedia.org/wiki/Gaussian_quadrature>`_ for integrating the space between :math:`\left<\frac{dH}{d\lambda}\right>` values for each :math:`\lambda` sampled.
-To use this method, please make sure that the simulations are performed at certain :math:`\lambda` values using fixed gaussian quadrature points (e.g., [He2020]_). Currently, up to 16 guassian quadrature points are supported (see the table below).
+To use this method, please make sure that the simulations are performed at certain :math:`\lambda` values using fixed gaussian quadrature points (e.g., [He2020]_). Currently, up to 16 gaussian quadrature points are supported (see the table below).
 
 .. list-table:: gaussian quadrature points
     :widths: 5 30
@@ -49,3 +49,4 @@ API Reference
 .. autoclass:: alchemlyb.estimators.TI_GQ
     :members:
     :inherited-members:
+    :no-index:

docs/parsing.rst

@@ -6,7 +6,7 @@
 Parsing data files
 ==================
 **alchemlyb** features parsing submodules for getting raw data from different software packages into common data structures that can be used directly by its :ref:`subsamplers <subsampling>` and :ref:`estimators <estimators>`.
-Each submodule features at least two functions, namely:
+Each submodule features some of the following functions, namely:
 
 :func:`extract_dHdl`
   Extract the gradient of the Hamiltonian, :math:`\frac{dH}{d\lambda}`, for each timestep of the sampled state.
@@ -241,4 +241,5 @@ See the documentation for the package you are using for more details on parser u
     gomc
     parquet
     lammps
+    util
 

docs/parsing/alchemlyb.parsing.amber.rst

@@ -1,6 +1,7 @@
 Amber parsing
 =============
 .. automodule:: alchemlyb.parsing.amber
+   :no-members:
 
 The parsers featured in this module are constructed to properly parse `Amber MD`_ output files containing derivatives of the Hamiltonian and FEP (BAR/MBAR) data.
 

docs/parsing/alchemlyb.parsing.gmx.rst

@@ -1,6 +1,7 @@
 Gromacs parsing
 ===============
 .. automodule:: alchemlyb.parsing.gmx
+   :no-members:
 
 The parsers featured in this module are constructed to properly parse XVG files containing Hamiltonian differences (for obtaining reduced potentials, :math:`u_{nk}`) and/or Hamiltonian derivatives (for obtaining gradients, :math:`\frac{dH}{d\lambda}`).
 To produce such a file from an existing EDR energy file, use ``gmx energy -f <.edr> -odh dhdl.xvg`` with your installation of `Gromacs`_.

docs/parsing/alchemlyb.parsing.gomc.rst

@@ -1,6 +1,7 @@
 GOMC parsing
 ==============
 .. automodule:: alchemlyb.parsing.gomc
+   :no-members:
 
 The parsers featured in this module are constructed to properly parse `GOMC <http://gomc.eng.wayne.edu/>`_ free energy output files, 
 containing the Hamiltonian derivatives (:math:`\frac{dH}{d\lambda}`) for TI-based estimators and Hamiltonian differences (:math:`\Delta H` 

docs/parsing/alchemlyb.parsing.lammps.rst

@@ -1,6 +1,7 @@
 LAMMPS Parsing
-=============
+==============
 .. automodule:: alchemlyb.parsing.lammps
+   :no-members:
 
 API Reference
 -------------

docs/parsing/alchemlyb.parsing.namd.rst

@@ -1,6 +1,7 @@
 NAMD parsing
 =============
 .. automodule:: alchemlyb.parsing.namd
+   :no-members:
 
 The parsers featured in this module are constructed to properly parse `NAMD`_ ``.fepout`` output files containing derivatives of the Hamiltonian and FEP (BAR) data.
 See the NAMD documentation for the `theoretical backdrop <https://www.ks.uiuc.edu/Research/namd/2.13/ug/node60.html>`_ and `implementation details <https://www.ks.uiuc.edu/Research/namd/2.13/ug/node61.html>`_.

docs/parsing/alchemlyb.parsing.util.rst

@@ -0,0 +1,11 @@
+Utility parsing functions
+=========================
+
+.. automodule:: alchemlyb.parsing.util
+   :no-members:
+
+API Reference
+-------------
+This submodule includes these utility functions:
+
+.. autofunction:: alchemlyb.parsing.util.anyopen

docs/postprocessors/alchemlyb.postprocessors.units.rst

@@ -1,7 +1,8 @@
-alchemlyb.postprocessors.units
+alchemlyb.postprocessors.units
 ==============================
 
 .. automodule:: alchemlyb.postprocessors.units
+   :no-members:
 
 Some examples are given here to illustrate how to use the unit converter
 functions to convert units. ::

docs/preprocessing/alchemlyb.preprocessing.subsampling.rst

@@ -4,6 +4,7 @@ Subsampling
 ===========
 
 .. automodule:: alchemlyb.preprocessing.subsampling
+   :no-members:
 
 The functions featured in this module can be used to easily subsample either
 :ref:`dHdl <dHdl>` or :ref:`u_nk <u_nk>` datasets to give less correlated

docs/workflows/alchemlyb.workflows.ABFE.rst

@@ -195,3 +195,4 @@ API Reference
 .. autoclass:: alchemlyb.workflows.ABFE
     :members:
     :inherited-members:
+    :no-index:

docs/workflows/alchemlyb.workflows.base.rst

@@ -1,6 +1,7 @@
 The base workflow
 =================
 .. automodule:: alchemlyb.workflows.base
+   :no-members:
 
 The :class:`alchemlyb.workflows.base.WorkflowBase` class provides a
 basic API template for the workflow development.  The workflow should
@@ -31,3 +32,4 @@ API Reference
 .. autoclass:: alchemlyb.workflows.base.WorkflowBase
     :members:
     :inherited-members:
+    :no-index:

src/alchemlyb/parsing/lammps.py

@@ -502,7 +502,7 @@ def extract_u_nk_from_u_n(
     column_lambda: int,
     column_U: int,
     column_U_cross: int,
-    dependence: Callable[[float], float] = lambda x: (x),
+    dependence: Callable[[float], float] = lambda x: x,
     index: int = -1,
     units: str = "real",
     prec: int = 4,
@@ -1023,7 +1023,7 @@ def extract_dHdl_from_u_n(
     T: float,
     column_lambda: int | None = None,
     column_u_cross: int | None = None,
-    dependence: Callable[[float], float] = lambda x: (1 / x),
+    dependence: Callable[[float], float] = lambda x: 1 / x,
     units: str = "real",
     prec: int = 4,
 ) -> pd.DataFrame:

src/alchemlyb/parsing/namd.py

@@ -173,7 +173,7 @@ def extract_u_nk(
         Support for Interleaved Double-Wide Sampling files added, with various
         robustness checks.
 
-        :param:`fep_files` can now be a list of filenames.
+        ``fep_files`` can now be a list of filenames.
 
     .. versionchanged:: 2.6.0
         Added parameter ignore_equilibration.

src/alchemlyb/parsing/util.py

@@ -7,6 +7,8 @@
 from os import PathLike
 from typing import TextIO
 
+__all__ = ["anyopen", "bz2_open", "gzip_open"]
+
 
 def bz2_open(filename: str, mode: str) -> TextIO:
     mode += "t" if mode in ["r", "w", "a", "x"] else ""

src/alchemlyb/visualisation/convergence.py

@@ -15,57 +15,57 @@ def plot_convergence(
 ) -> Axes:
     """Plot the forward and backward convergence.
 
-     The input could be the result from
-     :func:`~alchemlyb.convergence.forward_backward_convergence` or
-     :func:`~alchemlyb.convergence.fwdrev_cumavg_Rc`. The input should be a
-     :class:`pandas.DataFrame` which has column `Forward`, `Backward` and
-     :attr:`pandas.DataFrame.attrs` should compile with :ref:`note-on-units`.
-     The errorbar will be plotted if column `Forward_Error` and `Backward_Error`
-     is present.
+    The input could be the result from
+    :func:`~alchemlyb.convergence.forward_backward_convergence` or
+    :func:`~alchemlyb.convergence.fwdrev_cumavg_Rc`. The input should be a
+    :class:`pandas.DataFrame` which has column `Forward`, `Backward` and
+    :attr:`pandas.DataFrame.attrs` should compile with :ref:`note-on-units`.
+    The errorbar will be plotted if column `Forward_Error` and `Backward_Error`
+    is present.
 
-     `Forward`: A column of free energy estimate from the first X% of data,
-     where optional `Forward_Error` column is the corresponding error.
+    `Forward`: A column of free energy estimate from the first X% of data,
+    where optional `Forward_Error` column is the corresponding error.
 
-     `Backward`: A column of free energy estimate from the last X% of data.,
-     where optional `Backward_Error` column is the corresponding error.
+    `Backward`: A column of free energy estimate from the last X% of data.,
+    where optional `Backward_Error` column is the corresponding error.
 
     `final_error` is the error of the final value and is shown as the error band around the
     final value. It can be provided in case an estimate is available that is more appropriate
     than the default, which is the error of the last value in `Backward`.
 
-     Parameters
-     ----------
-     dataframe : Dataframe
-         Output Dataframe has column `Forward`, `Backward` or optionally
-         `Forward_Error`, `Backward_Error` see :ref:`plot_convergence <plot_convergence>`.
-     units : str
-         The unit of the estimate. The default is `None`, which is to use the
-         unit in the input. Setting this will change the output unit.
-     final_error : float
-         The error of the final value in ``units``. If not given, takes the last
-         error in `backward_error`.
-     ax : matplotlib.axes.Axes
-         Matplotlib axes object where the plot will be drawn on. If ``ax=None``,
-         a new axes will be generated.
-
-     Returns
-     -------
-     matplotlib.axes.Axes
-         An axes with the forward and backward convergence drawn.
-
-     Note
-     ----
-     The code is taken and modified from
-     `Alchemical Analysis <https://github.com/MobleyLab/alchemical-analysis>`_.
-
-
-     .. versionchanged:: 1.0.0
-         Keyword arg final_error for plotting a horizontal error bar.
-         The array input has been deprecated.
-         The units default to `None` which uses the units in the input.
-     .. versionchanged:: 0.6.0
-         data now takes in dataframe
-     .. versionadded:: 0.4.0
+    Parameters
+    ----------
+    dataframe : Dataframe
+        Output Dataframe has column `Forward`, `Backward` or optionally
+        `Forward_Error`, `Backward_Error` see :ref:`plot_convergence <plot_convergence>`.
+    units : str
+        The unit of the estimate. The default is `None`, which is to use the
+        unit in the input. Setting this will change the output unit.
+    final_error : float
+        The error of the final value in ``units``. If not given, takes the last
+        error in `backward_error`.
+    ax : matplotlib.axes.Axes
+        Matplotlib axes object where the plot will be drawn on. If ``ax=None``,
+        a new axes will be generated.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        An axes with the forward and backward convergence drawn.
+
+    Note
+    ----
+    The code is taken and modified from
+    `Alchemical Analysis <https://github.com/MobleyLab/alchemical-analysis>`_.
+
+
+    .. versionchanged:: 1.0.0
+        Keyword arg final_error for plotting a horizontal error bar.
+        The array input has been deprecated.
+        The units default to `None` which uses the units in the input.
+    .. versionchanged:: 0.6.0
+        data now takes in dataframe
+    .. versionadded:: 0.4.0
 
     """
     if units is not None:
@@ -160,50 +160,49 @@ def plot_block_average(
     final_error: None | float = None,
     ax: None | Axes = None,
 ) -> Axes:
-    """Plot the forward and backward convergence.
+    """Plot the block average free energy estimates.
 
-     The input could be the result from
-     :func:`~alchemlyb.convergence.forward_backward_convergence` or
-     :func:`~alchemlyb.convergence.fwdrev_cumavg_Rc`. The input should be a
-     :class:`pandas.DataFrame` which has column `FE` and
-     :attr:`pandas.DataFrame.attrs` should compile with :ref:`note-on-units`.
-     The errorbar will be plotted if column `FE_Error` and `Backward_Error`
-     is present.
+    The input could be the result from
+    :func:`~alchemlyb.convergence.block_average`. The input should be a
+    :class:`pandas.DataFrame` which has column `FE` and
+    :attr:`pandas.DataFrame.attrs` should compile with :ref:`note-on-units`.
+    The errorbar will be plotted if column `FE_Error`
+    is present.
 
-     `FE`: A column of free energy estimate from some X% block of the data,
-     where optional `FE_Error` column is the corresponding error.
+    `FE`: A column of free energy estimate from some X% block of the data,
+    where optional `FE_Error` column is the corresponding error.
 
     `final_error` is the error of the final value and is shown as the error band around the
     final value. It can be provided in case an estimate is available that is more appropriate
     than the default, which is the error of the last value in `Backward`.
 
-     Parameters
-     ----------
-     dataframe : Dataframe
-         Output Dataframe has column `Forward`, `Backward` or optionally
-         `Forward_Error`, `Backward_Error` see :ref:`plot_convergence <plot_convergence>`.
-     units : str
-         The unit of the estimate. The default is `None`, which is to use the
-         unit in the input. Setting this will change the output unit.
-     final_error : float
-         The error (standard deviation) of the final value in ``units``. If not given, takes the
-         overall error of the time blocks, unless these were not provided, it which case it
-         equals 1 kT.
-     ax : matplotlib.axes.Axes
-         Matplotlib axes object where the plot will be drawn on. If ``ax=None``,
-         a new axes will be generated.
-
-     Returns
-     -------
-     matplotlib.axes.Axes
-         An axes with the forward and backward convergence drawn.
-
-     Note
-     ----
-     The code is taken and modified from
-     `Alchemical Analysis <https://github.com/MobleyLab/alchemical-analysis>`_.
-
-     .. versionadded:: 2.4.0
+    Parameters
+    ----------
+    dataframe : Dataframe
+        Output Dataframe has column `FE`, or optionally
+        `FE_Error`.
+    units : str
+        The unit of the estimate. The default is `None`, which is to use the
+        unit in the input. Setting this will change the output unit.
+    final_error : float
+        The error (standard deviation) of the final value in ``units``. If not given, takes the
+        overall error of the time blocks, unless these were not provided, it which case it
+        equals 1 kT.
+    ax : matplotlib.axes.Axes
+        Matplotlib axes object where the plot will be drawn on. If ``ax=None``,
+        a new axes will be generated.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        An axes with the forward and backward convergence drawn.
+
+    Note
+    ----
+    The code is taken and modified from
+    `Alchemical Analysis <https://github.com/MobleyLab/alchemical-analysis>`_.
+
+    .. versionadded:: 2.4.0
 
     """
     if units is not None: