docs: fix API docstrings that don'tt render and broken example README

docs/source/examples.rst

@@ -4,7 +4,7 @@
 Examples
 ===================
 
-.. include:: ../../examples/README
+.. include:: ../examples/README
 
 .. This creates the links from the filenames within README to pages.
 .. _gaussianrecipe.py: examples/gaussianrecipe.html

news/docs-api-rendering-fixes.rst

@@ -0,0 +1,24 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* Fix API docstrings so code examples in ``RecipeOrganizer.add_soft_bounds`` and ``iterate_over_parameters`` render, and fix docstring formatting errors in ``ProfileParser``, ``PDFParser``, ``lognormal_spherical_particle``, and the ``interface`` module.
+* Fix broken include of the examples README in the examples documentation page.
+
+**Security:**
+
+* <news item>

src/diffpy/srfit/fitbase/profileparser.py

@@ -86,9 +86,9 @@ class ProfileParser(object):
         ``""``). The format string is a unique identifier for the data
         format handled by the parser.
     _banks : list of tuples
-        The data from each bank. Each bank contains a (x, y, dx,
-        dy)
+        The data from each bank. Each bank contains a (x, y, dx, dy)
         tuple:
+
         x : np.ndarray
             The independent variable read from the file.
         y : np.ndarray

src/diffpy/srfit/fitbase/recipeorganizer.py

@@ -282,8 +282,8 @@ def iterate_over_parameters(
 
         Examples
         --------
+        .. code-block:: python
 
-        ..
             for param in recipe.iterate_over_parameters(pattern="scale_"):
                 # print the name and value of parameters containing "scale_"
                 print(f"{param.name}={param.value}")
@@ -1427,7 +1427,8 @@ def add_soft_bounds(
         -----
         The penalty is calculated as:
 
-        ..
+        .. code-block:: python
+
             (max(0, lower_bound - val, val - upper_bound) / sig) ** 2
 
         where `val` is the value of the evaluated `param_or_eq`.
@@ -1439,7 +1440,9 @@ def add_soft_bounds(
         Restraining the lattice parameters of an Ni lattice to be
         approximately 7.4Å (2x the original lattice param)
         can be done with the following code:
-        ..
+
+        .. code-block:: python
+
             recipe.add_soft_bounds(
                 "a_ni + b_ni",
                 lower_bound=7.0,

src/diffpy/srfit/interface/interface.py

@@ -15,8 +15,8 @@
 """Interface enhancements for Parameter-type classes.
 
 Most interface additions can thought of by considering the classes in
-SrFit to be sets of parameters. "+=" adds a new parameter, when that
-makes sense. "|=" is the 'union' of these sets, and in general is used
+SrFit to be sets of parameters. ``+=`` adds a new parameter, when that
+makes sense. ``|=`` is the 'union' of these sets, and in general is used
 to combine different objects. See individual interface classes for
 specifics.
 """

src/diffpy/srfit/pdf/characteristicfunctions.py

@@ -334,19 +334,21 @@ def lognormal_spherical_particle(
     Here, r is the independent variable, mu is the mean of the
     distribution (not of the particle size), and s is the width of
     the distribution. This is the characteristic function for the
-    lognormal distribution of particle diameter:
+    lognormal distribution of particle diameter::
 
-    F(r, mu, s) = 0.5*Erfc((-mu-3*s^2+Log(r))/(sqrt(2)*s))
-               + 0.25*r^3*Erfc((-mu+Log(r))/(sqrt(2)*s))*exp(-3*mu-4.5*s^2)
-               - 0.75*r*Erfc((-mu-2*s^2+Log(r))/(sqrt(2)*s))*exp(-mu-2.5*s^2)
+        F(r, mu, s) = (
+            0.5*Erfc((-mu-3*s^2+Log(r))/(sqrt(2)*s))
+            + 0.25*r^3*Erfc((-mu+Log(r))/(sqrt(2)*s))*exp(-3*mu-4.5*s^2)
+            - 0.75*r*Erfc((-mu-2*s^2+Log(r))/(sqrt(2)*s))*exp(-mu-2.5*s^2)
+        )
 
     The expectation value of the distribution gives the average particle
     diameter, particle_diameter. The variance of the distribution gives
     particle_diameter_sigma^2. mu and s can be expressed in terms of these
-    as:
+    as::
 
-    s^2 = log((particle_diameter_sigma/particle_diameter)^2 + 1)
-    mu = log(particle_diameter) - s^2/2
+        s^2 = log((particle_diameter_sigma/particle_diameter)^2 + 1)
+        mu = log(particle_diameter) - s^2/2
 
     Source unknown.
 

src/diffpy/srfit/pdf/pdfparser.py

@@ -51,6 +51,7 @@ class PDFParser(ProfileParser):
     _banks
         The data from each bank. Each bank contains a
         (x, y, dx, dy) tuple:
+
         x
             A numpy array containing the independent
             variable read from the file.