diff --git a/docs/source/conf.py b/docs/source/conf.py index 6f33a1b7..da14b4ad 100644 --- a/docs/source/conf.py +++ b/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), +} diff --git a/news/documentation-metadata.rst b/news/documentation-metadata.rst new file mode 100644 index 00000000..3a124fc7 --- /dev/null +++ b/news/documentation-metadata.rst @@ -0,0 +1,23 @@ +**Added:** + +* No News Added: rebuild the documentation with proper metadata handling + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/diffpy/srfit/fitbase/fitrecipe.py b/src/diffpy/srfit/fitbase/fitrecipe.py index 4d7be2c9..e04f3af6 100644 --- a/src/diffpy/srfit/fitbase/fitrecipe.py +++ b/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) diff --git a/src/diffpy/srfit/fitbase/profile.py b/src/diffpy/srfit/fitbase/profile.py index 2600fb8f..6ab7190b 100644 --- a/src/diffpy/srfit/fitbase/profile.py +++ b/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 ------ diff --git a/src/diffpy/srfit/fitbase/profileparser.py b/src/diffpy/srfit/fitbase/profileparser.py index 32cb9669..902c70f6 100644 --- a/src/diffpy/srfit/fitbase/profileparser.py +++ b/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. """ diff --git a/src/diffpy/srfit/fitbase/simplerecipe.py b/src/diffpy/srfit/fitbase/simplerecipe.py index 81a0094a..9e7b5b94 100644 --- a/src/diffpy/srfit/fitbase/simplerecipe.py +++ b/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 ------ diff --git a/src/diffpy/srfit/pdf/pdfcontribution.py b/src/diffpy/srfit/pdf/pdfcontribution.py index bcd694ff..65ee5eda 100644 --- a/src/diffpy/srfit/pdf/pdfcontribution.py +++ b/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 ------ diff --git a/src/diffpy/srfit/pdf/pdfparser.py b/src/diffpy/srfit/pdf/pdfparser.py index 445835f7..1f836303 100644 --- a/src/diffpy/srfit/pdf/pdfparser.py +++ b/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+)?"} diff --git a/src/diffpy/srfit/sas/sasparser.py b/src/diffpy/srfit/sas/sasparser.py index 1ddd48b3..50c7f505 100644 --- a/src/diffpy/srfit/sas/sasparser.py +++ b/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 diff --git a/src/diffpy/srfit/sas/sasprofile.py b/src/diffpy/srfit/sas/sasprofile.py index a5ad4225..a05420ae 100644 --- a/src/diffpy/srfit/sas/sasprofile.py +++ b/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.