chore: rebuild the documentation with proper metadata handling

Author: stevenhua0320

docs/source/conf.py

@@ -77,7 +77,7 @@
 napoleon_custom_sections = [
     ("Managed Parameters", "Attributes"),
     ("Usable Metadata", "Attributes"),
-    ("General Metadata", "Attributes"),
+    ("General Metadata", "params_style"),
     ("Metadata", "Attributes"),
     ("Properties", "Attributes"),
     ("Operator Attributes", "Attributes"),
@@ -336,4 +336,7 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-# intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}

news/documentation-metadata.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No News Added: rebuild the documentation with proper metadata handling
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/srfit/fitbase/fitrecipe.py

@@ -292,15 +292,17 @@ def residual(self, p=[]):
         ----------
         p
             The list of current variable values, provided in the same order
-            as the '_parameters' list. If p is an empty iterable (default),
-            then it is assumed that the parameters have already been
-            updated in some other way, and the explicit update within this
-            function is skipped.
+            as the ``_parameters`` list. If ``p`` is an empty iterable
+            (default), then it is assumed that the parameters have already
+            been updated in some other way, and the explicit update within
+            this function is skipped.
 
+        Notes
+        -----
         The residual is by default the weighted concatenation of each
-        FitContribution's residual, plus the value of each restraint. The array
-        returned, denoted chiv, is such that
-        dot(chiv, chiv) = chi^2 + restraints.
+        :class:`FitContribution` residual, plus the value of each restraint.
+        The returned array ``chiv`` satisfies
+        ``dot(chiv, chiv) = chi^2 + restraints``.
         """
 
         # Prepare, if necessary
@@ -343,15 +345,17 @@ def scalarResidual(self, p=[]):
         ----------
         p
             The list of current variable values, provided in the same order
-            as the '_parameters' list. If p is an empty iterable (default),
-            then it is assumed that the parameters have already been
-            updated in some other way, and the explicit update within this
-            function is skipped.
+            as the ``_parameters`` list. If ``p`` is an empty iterable
+            (default), then it is assumed that the parameters have already
+            been updated in some other way, and the explicit update within
+            this function is skipped.
 
+        Notes
+        -----
         The residual is by default the weighted concatenation of each
-        FitContribution's residual, plus the value of each restraint. The array
-        returned, denoted chiv, is such that
-        dot(chiv, chiv) = chi^2 + restraints.
+        :class:`FitContribution` residual, plus the value of each restraint.
+        The returned array, denoted ``chiv``, is such that
+        ``dot(chiv, chiv) = chi^2 + restraints``.
         """
         chiv = self.residual(p)
         return dot(chiv, chiv)

src/diffpy/srfit/fitbase/profile.py

@@ -146,11 +146,16 @@ def setObservedProfile(self, xobs, yobs, dyobs=None):
             Numpy array of the observed signal.
         dyobs
             Numpy array of the uncertainty in the observed signal. If
-            dyobs is None (default), it will be set to 1 at each
-            observed xobs.
+            `dyobs` is None (default), it will be set to 1 at each
+            observed `xobs`.
 
-        Raises ValueError if len(yobs) != len(xobs)
-        Raises ValueError if dyobs != None and len(dyobs) != len(xobs)
+
+        Raises
+        -----------
+        ValueError
+            if len(yobs) != len(xobs)
+        ValueError
+            if dyobs != None and len(dyobs) != len(xobs)
         """
         if len(yobs) != len(xobs):
             raise ValueError("xobs and yobs are different lengths")
@@ -195,8 +200,8 @@ def setCalculationRange(self, xmin=None, xmax=None, dx=None):
             The sample spacing in the independent variable.  When different
             from the data, resample the ``x`` as anchored at ``xmin``.
 
-        Note that xmin is always inclusive (unless clipped). xmax is inclusive
-        if it is within the bounds of the observed data.
+        Note that ``xmin`` is always inclusive (unless clipped).
+        ``xmax`` is inclusive if it is within the bounds of the observed data.
 
         Raises
         ------

src/diffpy/srfit/fitbase/profileparser.py

@@ -105,7 +105,9 @@ def parseString(self, patstring):
         patstring
             A string containing the pattern
 
-        Raises ParseError if the string cannot be parsed
+        Raises
+        ----------
+        ParseError if the string cannot be parsed
         """
         raise NotImplementedError()
 
@@ -119,8 +121,12 @@ def parseFile(self, filename):
         filename
             The name of the file to parse
 
-        Raises IOError if the file cannot be read
-        Raises ParseError if the file cannot be parsed
+        Raises
+        ----------
+        IOError
+            if the file cannot be read
+        ParseError
+            if the file cannot be parsed
         """
         infile = open(filename, "r")
         self._banks = []
@@ -153,7 +159,10 @@ def selectBank(self, index):
         index
             index of bank (integer, starting at 0).
 
-        Raises IndexError if requesting a bank that does not exist
+        Raises
+        ----------
+        IndexError
+            if requesting a bank that does not exist
         """
         if index is None:
             index = self._meta.get("bank", 0)
@@ -187,6 +196,8 @@ def getData(self, index=None):
             index of bank (integer, starting at 0, default None). If
             index is None then the currently selected bank is used.
 
+        Returns
+        ----------
         This returns (x, y, dx, dy) tuple for the bank. dx is 0 if it cannot
         be determined from the data format.
         """

src/diffpy/srfit/fitbase/simplerecipe.py

@@ -130,9 +130,12 @@ def setObservedProfile(self, xobs, yobs, dyobs=None):
             dyobs is None (default), it will be set to 1 at each
             observed xobs.
 
-
-        Raises ValueError if len(yobs) != len(xobs)
-        Raises ValueError if dyobs != None and len(dyobs) != len(xobs)
+        Raises
+        ----------
+        ValueError
+            if len(yobs) != len(xobs)
+        ValueError
+            if dyobs != None and len(dyobs) != len(xobs)
         """
         return self.profile.setObservedProfile(xobs, yobs, dyobs)
 
@@ -146,20 +149,20 @@ def setCalculationRange(self, xmin=None, xmax=None, dx=None):
         Parameters
         ----------
 
-        xmin : float or "obs", optional
+        xmin : float or `obs`, optional
             The minimum value of the independent variable.  Keep the
             current minimum when not specified.  If specified as "obs"
             reset to the minimum observed value.
-        xmax : float or "obs", optional
+        xmax : float or `obs`, optional
             The maximum value of the independent variable.  Keep the
             current maximum when not specified.  If specified as "obs"
             reset to the maximum observed value.
-        dx : float or "obs", optional
+        dx : float or `obs`, optional
             The sample spacing in the independent variable.  When different
             from the data, resample the ``x`` as anchored at ``xmin``.
 
-        Note that xmin is always inclusive (unless clipped). xmax is inclusive
-        if it is within the bounds of the observed data.
+        Note that ``xmin`` is always inclusive (unless clipped).
+        ``xmax`` is inclusive if it is within the bounds of the observed data.
 
         Raises
         ------

src/diffpy/srfit/pdf/pdfcontribution.py

@@ -142,20 +142,20 @@ def setCalculationRange(self, xmin=None, xmax=None, dx=None):
         Parameters
         ----------
 
-        xmin : float or "obs", optional
+        xmin : float or `obs`, optional
             The minimum value of the independent variable.  Keep the
             current minimum when not specified.  If specified as "obs"
             reset to the minimum observed value.
-        xmax : float or "obs", optional
+        xmax : float or `obs`, optional
             The maximum value of the independent variable.  Keep the
             current maximum when not specified.  If specified as "obs"
             reset to the maximum observed value.
-        dx : float or "obs", optional
+        dx : float or `obs`, optional
             The sample spacing in the independent variable.  When different
             from the data, resample the ``x`` as anchored at ``xmin``.
 
-        Note that xmin is always inclusive (unless clipped). xmax is inclusive
-        if it is within the bounds of the observed data.
+        Note that ``xmin`` is always inclusive (unless clipped).
+        ``xmax`` is inclusive if it is within the bounds of the observed data.
 
         Raises
         ------

src/diffpy/srfit/pdf/pdfparser.py

@@ -120,7 +120,10 @@ def parseString(self, patstring):
         patstring
             A string containing the pattern
 
-        Raises ParseError if the string cannot be parsed
+        Raises
+        ----------
+        ParseError
+            if the string cannot be parsed
         """
         # useful regex patterns:
         rx = {"f": r"[-+]?(\d+(\.\d*)?|\d*\.\d+)([eE][-+]?\d+)?"}

src/diffpy/srfit/sas/sasparser.py

@@ -100,8 +100,12 @@ def parseFile(self, filename):
         filename
             The name of the file to parse
 
-        Raises IOError if the file cannot be read
-        Raises ParseError if the file cannot be parsed
+        Raises
+        ----------
+        IOError
+            if the file cannot be read
+        ParseError
+            if the file cannot be parsed
         """
         import sasdata.dataloader.loader as sas_dataloader
 
@@ -142,7 +146,10 @@ def parseString(self, patstring):
         patstring
             A string containing the pattern
 
-        Raises ParseError if the string cannot be parsed
+        Raises
+        ----------
+        ParseError
+            if the string cannot be parsed
         """
         # This calls on parseFile, as that is how the sas data loader works.
         import tempfile

src/diffpy/srfit/sas/sasprofile.py

@@ -101,16 +101,20 @@ def setObservedProfile(self, xobs, yobs, dyobs=None):
         Parameters
         ----------
         xobs
-            Numpy array of the independent variable
+            Numpy array of the independent variable.
         yobs
             Numpy array of the observed signal.
         dyobs
             Numpy array of the uncertainty in the observed signal. If
-            dyobs is None (default), it will be set to 1 at each
-            observed xobs.
-
-        Raises ValueError if len(yobs) != len(xobs)
-        Raises ValueError if dyobs != None and len(dyobs) != len(xobs)
+            ``dyobs`` is ``None`` (default), it will be set to 1 at each
+            observed ``xobs``.
+
+        Raises
+        ------
+        ValueError
+            If ``len(yobs) != len(xobs)``.
+        ValueError
+            If ``dyobs is not None`` and ``len(dyobs) != len(xobs)``.
         """
         Profile.setObservedProfile(self, xobs, yobs, dyobs)
         # Copy the arrays to the _datainfo attribute.