Discuss lite-functions and aliases in the coding guide

[namurphy]

This PR adds sections to the coding guide on lite functions and aliases. This is another excerpt from #1305.

[codecov[bot]]

Codecov Report

Merging #1658 (993cd45) into main (3f01e25) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #1658   +/-   ##
=======================================
  Coverage   97.22%   97.22%           
=======================================
  Files          85       85           
  Lines        8013     8013           
=======================================
  Hits         7791     7791           
  Misses        222      222           

Impacted Files	Coverage Δ
plasmapy/formulary/dielectric.py	100.00% <ø> (ø)
plasmapy/formulary/frequencies.py	100.00% <ø> (ø)
plasmapy/formulary/speeds.py	97.77% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[namurphy]

I have a little bit of a dilemma with these two sections. We're basically repeating/duplicating ourselves in three different locations for both aliases and lite-functions: (1) in the glossary, (2) in the summary for the aliases and lite-functions sections, and (3) here. It's going to be SUPER easy getting these three locations out of sync.

I don't think I have a "best solution" for this at the moment. My first thought would be to update locations 1 and 2 to have a very top-level summary and then refer to location 3 for additional details.

Yep, I'm worried about this too. My inclination for (1) and (2) has been to include only the information that is unlikely to change. The implementation details are the most likely to change, and those would be included in (3). This seems in alignment with your first thought above.

An even better idea, if possible, would be to have locations 1 and 2 automatically repeat the first paragraph of location 3.

We could potentially do this via a reST substitution, though we'd want to do :term:`alias` in (2) and (3) and not in (1). I'm hesitating since we could end up overengineering it at this point...though it could end up being useful to have this infrastructure in place (e.g., for parameter definitions for B, etc. in functions).

I think I'll go with the first thought for the time being.

[rocco8773]

I think I'll go with the first thought for the time being.

Sounds good to me. With that said, the alias and lite-function section descriptions for automodapi should be updated. Remember these are defined in the conf.py.

[namurphy]

@rocco8773 — I worked in most of the suggestions so please take another look!

I also noticed that codespell starting failing, presumably because of a new release. This PR includes an update on which words codespell should skip, so it will fix the failing tests.

[rocco8773]

Just waiting for the docs to finish building so I can do a final look over.

[namurphy]

pre-commit.ci autofix