Fix Sphinx documentation warnings

[munechika-koyo]

Summary

• improve Sphinx and reStructuredText formatting across API docstrings and model documentation
• correct mathematical notation, units, cross-references, and code examples
• fix several documentation typos and clarify parameter descriptions
• use explicit function evaluation for the laser polarization profile

Example changes

m^3 -> m\\ :sup:`3`
:math:`n_e` -> :math:`n_\mathrm{e}`
:math:`exp()` -> :math:`\exp\left(   \right)`

[jacklovell]

I think \\ :sup:`-3` is significantly less readable than ^-3 in docstrings. It might look better in the HTML documentation, but when working with the source code or when in a python REPL calling help() it hurts readability.

Since most cases of :sup: are for raising to an integral power, why not instead use unicode?

^2 --> ² (U+00B2)
^3 --> ³ (U+00B3)
^- --> ⁻ (U+207B)

(U+207<n>) give superscript digits from 4 to 9 as well as + and - so should cater for most cases. Similarly, (U+208<n>) give subscript digits and (U+209) subscript letters to cover most use cases.

I actually think readability of docstrings/comments in source code is more important than strict typographical correctness, as long as the HTML renders "well enough." For RST in the ./docs folder that will realistically only ever be viewed as HTML it is good to stick to semantic correctness, but not elsewhere in the code at the expense of readability. For a similar reason, I would prefer \exp() in a docstring instead of \exp\left( \right) unless the resulting HTML looks terrible. And while n_\mathrm{e} is technically more correct than n_e, the latter is definitely easier to read in raw format (though better still may be nₑ using U+2091).

One thing which would help is by converting docstrings with LaTeX expressions to raw strings r""" to avoid having a load of double backslashes.

[jacklovell]

I also wonder whether some of the more equation-heavy docstrings would be better split up: have sections in the relevant rst file in ./docs which contain all the maths and make the docstring itself focus more on the API with perhaps a reference to the appropriate bit of the documentation. Realistically, how many people are going to be able to parse this when looking at it in a REPL or a text editor?

n(x, y, z) = \frac{R}{2\pi v_0 \sigma_x\sigma_y} \exp\left(-\frac{1}{2}\left(\frac{x^2}{\sigma_x^2}+\frac{y^2}{\sigma_y^2}\right)\right)\exp\left(-\int_{0}^{z}\frac{S(z')}{v_0}dz'\right),
\sigma_x = \sqrt{\sigma^2 + (ztg(\alpha_x))^2},\quad\sigma_y = \sqrt{\sigma^2 + (ztg(\alpha_y))^2},

@munechika-koyo can you create an issue where we can discuss this further before revisiting this PR, if there isn't one already?

[munechika-koyo]

Using a Unicode suffix/superscript looks much better if available.
I will try to use them as much as possible.

I also wonder whether some of the more equation-heavy docstrings would be better split up...

I agree with you.
I think what is important when reading the docstrings is understanding how to use the API.
Some APIs have docstrings that include equations (like numpy.gradient), but they are written at the bottom of the docstrings as a Note section.

@munechika-koyo can you create an issue where we can discuss this further before revisiting this PR, if there isn't one already?

Sure, I will.

[munechika-koyo]

Created #516 to discuss the docstring/documentation split and formatting guidelines before revisiting this PR.