DOC: fft.{fht, ifht}: add new examples

[Elle-Musoke]

Add new examples to fht and ifht docstrings. Create example subsections on fht because it now has two examples.

[docs only]

Reference issue

#7168

What does this implement/fix?

This change adds an example to the ifht docstring and a second, simpler example to the fht docstring.

Additional information

Tech notes: Hankel transforms are new to me, so please keep an eagle eye out for incorrect logic.

Doc notes:
Please correct me if the following aren't the way things are done in the SciPy doc.

• I added the new simple fht example above the longer, more conceptual example. This way new users will encounter it first and experienced users will know enough to scroll past it.
• I also couldn't find a reference for how to separate multiple examples in the same docstring, so I used bold titles for each.

AI Generation Disclosure

No AI tools used

[Elle-Musoke]

@mdhaber You gave me some really helpful tips on my first docstring example pull request. Would you mind having a look over my doc-related questions in the Additional Information section of this one?

[Elle-Musoke]

@lucascolley I incorporated your suggestions with the exception of the spaces around the / operator (I'm following the guidance in scientific-python/specs#326). Thanks!

[Elle-Musoke]

@lucascolley I missed one of your suggestions the other week, but it's in now. What do you think?

[lucascolley]

Hi @ntessore, could we possibly trouble you to check that this is correct?

[ntessore]

Apologies for the delay. The function evaluates the FHT on a logarithmic grid of values $k$ such that $kr$ = const. and returns function values $F(k)$ in ascending order of $k$. So the statement is correct but it took me a second to understand that it is correct. Maybe there is an easier way to say what's going on here?

[lucascolley]

Apologies for the delay. The function evaluates the FHT on a logarithmic grid of values k such that k r = const. and returns function values F ( k ) in ascending order of k . So the statement is correct but it took me a second to understand that it is correct. Maybe there is an easier way to say what's going on here?

@Elle-Musoke can you think of an easier way? Either way, let's get this in for 1.18.0.