Towards sphinx >= 3 (#3438)

Fixes #3224 
Fixes #2667
Co-authored-by: Lily Wang <[email protected]>
Co-authored-by: Oliver Beckstein <[email protected]>
Co-authored-by: richard <[email protected]>

.github/workflows/gh-ci.yaml

@@ -217,7 +217,7 @@ jobs:
     - name: install_deps
       run: |
         conda_deps="${{ env.MDA_CONDA_MIN_DEPS }} ${{ env.MDA_CONDA_EXTRA_DEPS}}"
-        pip_deps="${{ env.MDA_PIP_MIN_DEPS}} ${{ env.MDA_PIP_EXTRA_DEPS }} sphinx==1.8.5 sphinx-sitemap sphinx_rtd_theme msmb_theme==1.2.0"
+        pip_deps="${{ env.MDA_PIP_MIN_DEPS}} ${{ env.MDA_PIP_EXTRA_DEPS }} sphinx sphinx-sitemap sphinx_rtd_theme msmb_theme==1.2.0"
         mamba install ${conda_deps}
         pip install ${pip_deps}
 
@@ -227,7 +227,7 @@ jobs:
 
     - name: build_docs
       run: |
-        cd package && python setup.py build_sphinx -E
+        cd package && python setup.py build_sphinx -E --keep-going
 
     - name: deploy_docs
       if: github.event_name != 'pull_request'

package/CHANGELOG

@@ -13,7 +13,7 @@ The rules for this file:
   * release numbers follow "Semantic Versioning" http://semver.org
 
 ------------------------------------------------------------------------------
-??/??/?? IAlibay, melomcr, mdd31, ianmkenney, richardjgowers, hmacdope
+??/??/?? IAlibay, melomcr, mdd31, ianmkenney, richardjgowers, hmacdope, orbeckst
 
  * 2.1.0
 
@@ -22,6 +22,7 @@ Fixes
   * TRRWriter preserves timestep data (Issue #3350).
   * Fixed Universe creation from a custom object which only provided a topology,
     previously raised a TypeError. (Issue #3443)
+  * Documentation fixes (Issues #3224, #2667)
 
 Enhancements
   * Add option for custom compiler flags for C/C++ on build and remove march

package/MDAnalysis/analysis/density.py

@@ -102,13 +102,6 @@
    :members:
    :inherited-members: run
 
-   .. attribute:: results.density
-
-      After the analysis (see the :meth:`~DensityAnalysis.run` method), the
-      resulting density is stored in the :attr:`results.density` attribute as
-      a :class:`Density` instance. Note: this replaces the now deprecated
-      :attr:`density` attribute.
-
    .. automethod:: _set_user_grid
 
 
@@ -217,6 +210,11 @@ class DensityAnalysis(AnalysisBase):
             A :class:`Density` instance containing a physical density of units
             :math:`Angstrom^{-3}`.
 
+            After the analysis (see the :meth:`~DensityAnalysis.run` method),
+            the resulting density is stored in the :attr:`results.density`
+            attribute as a :class:`Density` instance. Note: this replaces the
+            now deprecated :attr:`density` attribute.
+
     density : :class:`Density`
             Alias to the :attr:`results.density`.
 
@@ -396,6 +394,7 @@ class DensityAnalysis(AnalysisBase):
        :func:`_set_user_grid` is now a method of :class:`DensityAnalysis`.
        :class:`Density` results are now stored in a
        :class:`MDAnalysis.analysis.base.Results` instance.
+
     """
 
     def __init__(self, atomgroup, delta=1.0,

package/MDAnalysis/analysis/encore/similarity.py

@@ -20,7 +20,8 @@
 # MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
 # J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
 #
-"""=================================================================================
+"""
+=================================================================================
 Ensemble Similarity Calculations --- :mod:`MDAnalysis.analysis.encore.similarity`
 =================================================================================
 
@@ -157,11 +158,13 @@
 ==================================
 
 .. autofunction:: hes
+   :noindex:
 
 .. autofunction:: ces
+   :noindex:
 
 .. autofunction:: dres
-
+   :noindex:
 
 Function reference
 ==================

package/MDAnalysis/analysis/hole2/hole.py

@@ -560,7 +560,7 @@ class HoleAnalysis(AnalysisBase):
 
     .. versionchanged:: 2.0.0
         :attr:`sphpdbs`, :attr:`outfiles` and :attr:`profiles `
-        are now stored in a :class:`MDAnalysis.analysis.base.Results` 
+        are now stored in a :class:`MDAnalysis.analysis.base.Results`
         instance.
 
     """
@@ -1300,14 +1300,14 @@ def bin_radii(self, frames=None, bins=100, range=None):
             Profiles to include by frame. If ``None``, includes
             all frames.
         bins : int or iterable of edges, optional
-            If bins is an int, it defines the number of equal-width bins in the given 
-            range. If bins is a sequence, it defines a monotonically increasing array of 
+            If bins is an int, it defines the number of equal-width bins in the given
+            range. If bins is a sequence, it defines a monotonically increasing array of
             bin edges, including the rightmost edge, allowing for non-uniform bin widths.
         range : (float, float), optional
             The lower and upper range of the bins.
             If not provided, ``range`` is simply ``(a.min(), a.max())``,
             where ``a`` is the array of reaction coordinates.
-            Values outside the range are ignored. The first element of the range must be 
+            Values outside the range are ignored. The first element of the range must be
             less than or equal to the second.
 
 
@@ -1358,14 +1358,14 @@ def histogram_radii(self, aggregator=np.mean, frames=None,
             Profiles to include by frame. If ``None``, includes
             all frames.
         bins : int or iterable of edges, optional
-            If bins is an int, it defines the number of equal-width bins in the given 
-            range. If bins is a sequence, it defines a monotonically increasing array of 
+            If bins is an int, it defines the number of equal-width bins in the given
+            range. If bins is a sequence, it defines a monotonically increasing array of
             bin edges, including the rightmost edge, allowing for non-uniform bin widths.
         range : (float, float), optional
             The lower and upper range of the bins.
             If not provided, ``range`` is simply ``(a.min(), a.max())``,
             where ``a`` is the array of reaction coordinates.
-            Values outside the range are ignored. The first element of the range must be 
+            Values outside the range are ignored. The first element of the range must be
             less than or equal to the second.
 
 
@@ -1394,14 +1394,14 @@ def plot_mean_profile(self, bins=100, range=None,
             Profiles to include by frame. If ``None``, includes
             all frames.
         bins : int or iterable of edges, optional
-            If bins is an int, it defines the number of equal-width bins in the given 
-            range. If bins is a sequence, it defines a monotonically increasing array of 
+            If bins is an int, it defines the number of equal-width bins in the given
+            range. If bins is a sequence, it defines a monotonically increasing array of
             bin edges, including the rightmost edge, allowing for non-uniform bin widths.
         range : (float, float), optional
             The lower and upper range of the bins.
             If not provided, ``range`` is simply ``(a.min(), a.max())``,
             where ``a`` is the array of reaction coordinates.
-            Values outside the range are ignored. The first element of the range must be 
+            Values outside the range are ignored. The first element of the range must be
             less than or equal to the second.
         color : str or array-like, optional
             Color for the plot.

package/MDAnalysis/analysis/pca.py

@@ -208,14 +208,6 @@ class PCA(AnalysisBase):
                 Will be removed in MDAnalysis 3.0.0. Please use
                 :attr:`results.cumulated_variance` instead.
 
-
-    Methods
-    -------
-    transform(atomgroup, n_components=None)
-        Take an atomgroup or universe with the same number of atoms as was
-        used for the calculation in :meth:`PCA.run`, and project it onto the
-        principal components.
-
     Notes
     -----
     Computation can be sped up by supplying precalculated mean positions.

package/MDAnalysis/coordinates/FHIAIMS.py

@@ -63,10 +63,6 @@
 Classes
 -------
 
-.. autoclass:: Timestep
-   :members:
-   :inherited-members:
-
 .. autoclass:: FHIAIMSReader
    :members:
    :inherited-members:

package/MDAnalysis/coordinates/GRO.py

@@ -52,9 +52,6 @@
 Classes
 -------
 
-.. autoclass:: Timestep
-   :members:
-
 .. autoclass:: GROReader
    :members:
 

package/MDAnalysis/coordinates/TRZ.py

@@ -38,45 +38,6 @@
 Classes
 -------
 
-.. autoclass:: MDAnalysis.coordinates.TRZ.Timestep
-   :members:
-
-   .. attribute:: frame
-
-      Index of current frame number (0 based)
-
-   .. attribute:: time
-
-      Current system time in ps
-
-   .. attribute:: n_atoms
-
-      Number of atoms in the frame (will be constant throughout trajectory)
-
-   .. attribute:: pressure
-
-      System pressure in pascals
-
-   .. attribute:: pressure_tensor
-
-      Array containing pressure tensors in order: xx, xy, yy, xz, yz, zz
-
-   .. attribute:: total_energy
-
-      Hamiltonian for the system in kJ/mol
-
-   .. attribute:: potential_energy
-
-      Potential energy of the system in kJ/mol
-
-   .. attribute:: kinetic_energy
-
-      Kinetic energy of the system in kJ/mol
-
-   .. attribute:: temperature
-
-      Temperature of the system in Kelvin
-
 .. autoclass:: TRZReader
    :members:
 
@@ -101,8 +62,8 @@ class TRZReader(base.ReaderBase):
 
     Attributes
     ----------
-    ts : TRZ.Timestep
-         :class:`~MDAnalysis.coordinates.TRZ.Timestep` object containing
+    ts : base.Timestep
+         :class:`~MDAnalysis.coordinates.base.Timestep` object containing
          coordinates of current frame
 
     Note

package/MDAnalysis/core/topology.py

@@ -114,7 +114,7 @@ def make_downshift_arrays(upshift, nparents):
     """
     if not len(upshift):
         return np.array([], dtype=object)
-        
+
     order = np.argsort(upshift)
 
     upshift_sorted = upshift[order]
@@ -178,30 +178,9 @@ class TransTable(object):
         number of residues in topology
     n_segments : int
         number of segments in topology
-    size
-        tuple describing the shape of the TransTable
-
-    Methods
-    -------
-    atoms2residues(aix)
-        Returns the residue index for many atom indices
-    residues2atoms_1d(rix)
-        All atoms in the residues represented by *rix*
-    residues2atoms_2d(rix)
-        List of atom indices for each residue in *rix*
-    residues2segments(rix)
-        Segment indices for each residue in *rix*
-    segments2residues_1d(six)
-        Similar to `residues2atoms_1d`
-    segments2residues_2d(six)
-        Similar to `residues2atoms_2d`
-    atoms2segments(aix)
-        Segment indices for each atom in *aix*
-    segments2atoms_1d(six)
-        Similar to `residues2atoms_1d`
-    segments2atoms_2d(six)
-        Similar to `residues2atoms_2d`
-
+    size : tuple
+        tuple ``(n_atoms, n_residues, n_segments)`` describing the shape of
+        the TransTable
     """
     def __init__(self,
                  n_atoms, n_residues, n_segments,  # Size of tables
@@ -236,7 +215,10 @@ def copy(self):
 
     @property
     def size(self):
-        """The shape of the table, (n_atoms, n_residues, n_segments)"""
+        """The shape of the table, ``(n_atoms, n_residues, n_segments)``.
+
+        :meta private:
+        """
         return (self.n_atoms, self.n_residues, self.n_segments)
 
     def atoms2residues(self, aix):
@@ -597,4 +579,4 @@ def add_Segment(self, **new_attrs):
             attr.values = np.concatenate([attr.values, np.array([newval])])
 
         return segidx
-        
+