fix: fix format of docstring to have no warning in html build

docs/source/api/diffpy.utils.rst

@@ -44,14 +44,6 @@ diffpy.utils.tools module
     :undoc-members:
     :show-inheritance:
 
-diffpy.utils.user_config module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. automodule:: diffpy.utils.user_config
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 diffpy.utils.diffraction_objects module
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

news/html-build.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No News Added: Fix format of docs to build html
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/utils/diffraction_objects.py

@@ -108,18 +108,18 @@ def __init__(
 
         Parameters
         ----------
-        xarray : ndarray
+        xarray : ``ndarray``
             The independent variable array containing "q", "tth", or "d" values.
-        yarray : ndarray
+        yarray : ``ndarray``
             The dependent variable array corresponding to intensity values.
         xtype : str
             The type of the independent variable in `xarray`. Must be one of
             {*XQUANTITIES}.
-        wavelength : float, optional, default is None.
+        wavelength : float, ``optional``, default is None.
             The wavelength of the incoming beam, specified in angstroms (Å)
-        scat_quantity : str, optional, default is an empty string "".
+        scat_quantity : str, ``optional``, default is an empty string "".
             The type of scattering experiment (e.g., "x-ray", "neutron").
-        name : str, optional, default is an empty string "".
+        name : str, ``optional``, default is an empty string "".
             The name or label for the scattering data.
         metadata : dict, optional, default is an empty dictionary {}
             The additional metadata associated with the diffraction object.
@@ -360,7 +360,7 @@ def all_arrays(self):
 
         Returns
         -------
-        ndarray
+        ``ndarray``
             The shape (len(data), 4) 2D array with columns containing the `
             yarray` (intensity) and the `xarray` values in q, tth, and d.
 
@@ -386,7 +386,7 @@ def input_xtype(self):
         Returns
         -------
         input_xtype : str
-            The type of `xarray`, which must be one of {*XQUANTITIES}.
+            The type of `xarray`, which must be one of ``{*XQUANTITIES}``.
         """
         return self._input_xtype
 
@@ -400,7 +400,7 @@ def uuid(self):
 
         Returns
         -------
-        uuid : UUID
+        uuid : ``UUID``
             The unique identifier of the DiffractionObject instance.
         """
         return self._uuid
@@ -478,7 +478,7 @@ def on_q(self):
 
         Returns
         -------
-        (q-array, y-array) : tuple of ndarray
+        (q-array, y-array) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with q and y data
         """
         return [self.all_arrays[:, 1], self.all_arrays[:, 0]]
@@ -488,7 +488,7 @@ def on_tth(self):
 
         Returns
         -------
-        (tth-array, y-array) : tuple of ndarray
+        (tth-array, y-array) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with tth and y data
         """
         return [self.all_arrays[:, 2], self.all_arrays[:, 0]]
@@ -498,7 +498,7 @@ def on_d(self):
 
         Returns
         -------
-        (d-array, y-array) : tuple of ndarray
+        (d-array, y-array) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with d and y data
         """
         return [self.all_arrays[:, 3], self.all_arrays[:, 0]]
@@ -522,12 +522,12 @@ def scale_to(
         target_diff_object: DiffractionObject
             The diffraction object you want to scale the current one onto.
 
-        q, tth, d : float, optional, default is None
+        q, tth, d : float, ``optional``, default is None
             The value of the x-array where you want the curves to line up
             vertically. Specify a value on one of the allowed grids, q, tth,
             or d), e.g., q=10.
 
-        offset : float, optional, default is None
+        offset : float, ``optional``, default is None
             The offset to add to the scaled y-values.
 
         Returns
@@ -574,16 +574,16 @@ def on_xtype(self, xtype):
         ----------
         xtype : str
             The type of quantity for the independent variable chosen from
-            {*XQUANTITIES, }
+            ``{*XQUANTITIES, }``
 
         Raises
         ------
         ValueError
-            Raised when the specified xtype is not among {*XQUANTITIES, }
+            Raised when the specified xtype is not among ``{*XQUANTITIES, }``
 
         Returns
         -------
-        (xarray, yarray) : tuple of ndarray
+        (xarray, yarray) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with x and y data for
             the specified xtype.
         """
@@ -604,9 +604,9 @@ def dump(self, filepath, xtype=None):
         ----------
         filepath : str
             The filepath where the diffraction object will be dumped
-        xtype : str, optional, default is q
+        xtype : str, ``optional``, default is q
             The type of quantity for the independent variable chosen from
-            {*XQUANTITIES, }
+            ``{*XQUANTITIES, }``
 
         Examples
         --------

src/diffpy/utils/resampler.py

@@ -30,11 +30,11 @@ def wsinterp(x, xp, fp, left=None, right=None):
 
     Parameters
     ----------
-    x: ndarray
+    x: ``ndarray``
         The x values at which interpolation is computed.
-    xp: ndarray
+    xp: ``ndarray``
         The array of known x values.
-    fp: ndarray
+    fp: ``ndarray``
         The array of y values associated with xp.
     left: float
         If given, set fp for x < xp[0] to left. Otherwise, if left is None
@@ -46,7 +46,7 @@ def wsinterp(x, xp, fp, left=None, right=None):
 
     Returns
     -------
-    ndarray or float
+    ``ndarray`` or float
         The interpolated values at points x. Returns a single float if x is a
         scalar, otherwise returns a numpy.ndarray.
     """
@@ -91,9 +91,9 @@ def nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None):
 
     Parameters
     ----------
-    xp: ndarray
+    xp: ``ndarray``
         The array of known x values.
-    fp: ndarray
+    fp: ``ndarray``
         The array of y values associated with xp.
     qmin: float
         The lower band limit in the frequency domain.
@@ -102,7 +102,7 @@ def nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None):
 
     Returns
     -------
-    x: ndarray
+    x: ``ndarray``
         The Nyquist-Shannon grid computed for the given qmin and qmax.
     fp_at_x: ndarray
         The interpolated values at points x. Returns a single float if x is a
@@ -139,7 +139,7 @@ def resample(r, s, dr):
 
     Returns
     -------
-    Returns resampled (r, s).
+    Returns resampled ``(r, s)``.
     """
 
     warnings.warn(

src/diffpy/utils/tools.py

@@ -51,43 +51,46 @@ def _load_config(file_path):
 
 
 def get_user_info(owner_name=None, owner_email=None, owner_orcid=None):
-    """Get name, email, and orcid of the owner/user from various sources and
+    """Get name, email, and ORCID of the owner/user from various sources and
     return it as a metadata dictionary.
 
-    The function looks for the information in json format configuration files
-    with the name 'diffpyconfig.json'. These can be in the user's home
-    directory and in the current working directory.  The information in the
-    config files are combined, with the local config overriding the
-    home- directory one.  Values for owner_name, owner_email, and owner_orcid
-    may be passed in to the function and these override the values in the
-    config files.
-
-    A template for the config file is below.  Create a text file called '
-    diffpyconfig.json' in your home directory and copy-paste the template
-    into it, editing it with your real information.
-    {
-      "owner_name": "<your name as you would like it stored with your data>>",
-      "owner_email": "<your_associated_email>>@email.com",
-      "owner_orcid": "<your_associated_orcid if you would like this stored with your data>>"  # noqa: E501
-    }
+    The function looks for information in JSON configuration files named
+    ``diffpyconfig.json``. These can be in the user's home directory and in
+    the current working directory. The information in the config files is
+    combined, with the local config overriding the home-directory one.
+    Values for ``owner_name``, ``owner_email``, and ``owner_orcid`` may be
+    passed in to the function, and these override the config files.
+
+    A template for the config file is below. Create a text file called
+    ``diffpyconfig.json`` in your home directory and paste the template into
+    it, editing it with your real information::
+
+        {
+          "owner_name": "<your name as you would like it stored with your data>",
+          "owner_email": "<your_associated_email>@email.com",
+          "owner_orcid": "<your_associated_orcid if you would like this stored with your data>" # noqa: E501
+        }
+
     You may also store any other global-level information that you would like
-    associated with your diffraction data in this file
+    associated with your diffraction data in this file.
 
     Parameters
     ----------
-    owner_name : str, optional, default is the value stored in the global or
-        local config file. The name of the user who will show as owner in the
-        metadata that is stored with the data
-    owner_email : str, optional, default is the value stored in the global or
-        local config file. The email of the user/owner
-    owner_orcid : str, optional, default is the value stored in the global or
-        local config file. The ORCID id of the user/owner
+    owner_name : str, ``optional``
+        Default is the value stored in the global or local config file.
+        The name of the user stored in metadata.
+    owner_email : str, ``optional``
+        Default is the value stored in the global or local config file.
+        The email address of the user/owner.
+    owner_orcid : str, ``optional``
+        Default is the value stored in the global or local config file.
+        The ORCID ID of the user/owner.
 
     Returns
     -------
     user_info : dict
-        The dictionary containing username, email and orcid of the user/owner
-        , and any other information stored in the global or local config files.
+        Dictionary containing username, email, ORCID, and any other
+        information stored in global or local config files.
     """
     runtime_info = {
         "owner_name": owner_name,
@@ -127,9 +130,9 @@ def check_and_build_global_config(skip_config_creation=False):
 
     Parameters
     ----------
-    skip_config_creation : bool, optional, default is False.
+    skip_config_creation : bool, ``optional``
         The boolean that will override the creation workflow even if no
-        config file exists.
+        config file exists. Default is False.
 
     Returns
     -------
@@ -190,6 +193,7 @@ def get_package_info(package_names, metadata=None):
     Package info stored in metadata as
     {'package_info': {'package_name': 'version_number'}}.
 
+    Parameters
     ----------
     package_name : str or list
         The name of the package(s) to retrieve the version number for.
@@ -244,11 +248,13 @@ def compute_mu_using_xraydb(
         The chemical formula of the material.
     energy : float
         The energy of the incident x-rays in keV.
-    sample_mass_density : float, optional, Default is None
+    sample_mass_density : float, ``optional``
         The mass density of the packed powder/sample in g/cm*3.
-    packing_fraction : float, optional, Default is None
+        Default is None.
+    packing_fraction : float, ``optional``
         The fraction of sample in the capillary (between 0 and 1).
         Specify either sample_mass_density or packing_fraction but not both.
+        Default is None.
 
     Returns
     -------