From e27a698de7cd1aebafcf2f468397bc031a1e6d3e Mon Sep 17 00:00:00 2001 From: Caden Myers Date: Thu, 15 Oct 2026 09:47:54 -0400 Subject: [PATCH] docs: fix API docstrings that don'tt render and broken example README --- docs/source/examples.rst | 2 +- news/docs-api-rendering-fixes.rst | 24 +++++++++++++++++++ src/diffpy/srfit/fitbase/profileparser.py | 4 ++-- src/diffpy/srfit/fitbase/recipeorganizer.py | 9 ++++--- src/diffpy/srfit/interface/interface.py | 4 ++-- .../srfit/pdf/characteristicfunctions.py | 16 +++++++------ src/diffpy/srfit/pdf/pdfparser.py | 1 + 7 files changed, 45 insertions(+), 15 deletions(-) create mode 100644 news/docs-api-rendering-fixes.rst diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 6e0ea9fa..a5134288 100644 --- a/docs/source/examples.rst +++ b/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 diff --git a/news/docs-api-rendering-fixes.rst b/news/docs-api-rendering-fixes.rst new file mode 100644 index 00000000..3ac6dbcd --- /dev/null +++ b/news/docs-api-rendering-fixes.rst @@ -0,0 +1,24 @@ +**Added:** + +* + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**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:** + +* diff --git a/src/diffpy/srfit/fitbase/profileparser.py b/src/diffpy/srfit/fitbase/profileparser.py index f810f2ca..39823c58 100644 --- a/src/diffpy/srfit/fitbase/profileparser.py +++ b/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 diff --git a/src/diffpy/srfit/fitbase/recipeorganizer.py b/src/diffpy/srfit/fitbase/recipeorganizer.py index 664fd7a8..2649e2bf 100644 --- a/src/diffpy/srfit/fitbase/recipeorganizer.py +++ b/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, diff --git a/src/diffpy/srfit/interface/interface.py b/src/diffpy/srfit/interface/interface.py index cf0bcdce..bd212497 100644 --- a/src/diffpy/srfit/interface/interface.py +++ b/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. """ diff --git a/src/diffpy/srfit/pdf/characteristicfunctions.py b/src/diffpy/srfit/pdf/characteristicfunctions.py index 1acc5921..7d5a2cf9 100644 --- a/src/diffpy/srfit/pdf/characteristicfunctions.py +++ b/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. diff --git a/src/diffpy/srfit/pdf/pdfparser.py b/src/diffpy/srfit/pdf/pdfparser.py index e9655a3b..10439160 100644 --- a/src/diffpy/srfit/pdf/pdfparser.py +++ b/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.