Invalid escape sequences in docstrings

[MitchellAcoustics]

Upon import (from acoustic_toolbox import Signal), several warnings are raised about invalid escape sequences in the standards docstrings, but otherwise it imports fine. Looks like it's related to the math sections. Need to check through sphinx to see if we're missing a math extension or something.

/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_tr_25417_2007.py:14: SyntaxWarning: invalid escape sequence '\c'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_tr_25417_2007.py:51: SyntaxWarning: invalid escape sequence '\m'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_tr_25417_2007.py:96: SyntaxWarning: invalid escape sequence '\c'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_tr_25417_2007.py:184: SyntaxWarning: invalid escape sequence '\c'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iec_61260_1_2014.py:153: SyntaxWarning: invalid escape sequence '\l'
  """Determine the band index `x` from a given frequency.
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_9613_1_1993.py:54: SyntaxWarning: invalid escape sequence '\c'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_9613_1_1993.py:92: SyntaxWarning: invalid escape sequence '\c'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_9613_1_1993.py:118: SyntaxWarning: invalid escape sequence '\c'
  """
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_1996_2_2007.py:70: SyntaxWarning: invalid escape sequence '\l'
  """Total sound pressure level of the tones in a critical band given the level of each of the tones.
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_1996_2_2007.py:82: SyntaxWarning: invalid escape sequence '\D'
  """Masking noise level :math:`L_{pn}`
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_1996_2_2007.py:124: SyntaxWarning: invalid escape sequence '\D'
  """Tonal audibility.
/Users/mitch/Documents/Trials/acoustic_toolbox_test2/.venv/lib/python3.12/site-packages/acoustic_toolbox/standards/iso_1996_2_2007.py:248: SyntaxWarning: invalid escape sequence '\D'
  """Effective analysis bandwidth.

[Nitnelav]

Yeah I saw that too, but the math equations don't seem to be affected, so I left it as is. There might be a way to remove those warnings though

[MitchellAcoustics]

I was considering switching the documentation over to mkdocs rather than sphinx - I find it much nicer to write and work in and the mkdocs-material theme looks really nice (although rtd-theme is also available). I used mkdocs for my circumplex package: https://circumplex.readthedocs.io/en/latest/. A big part is I just hate writing ReST/sphinx docstrings and find Google/Numpy style with straightforward markdown in the docs nicer. But that's very much personal taste, so I didn't want to just go ahead with it.

What do you think? It'd handle this issue at the same time.

[Nitnelav]

I am quite new to this way of writing docs so I'm fine with anything you might prefer.
Maybe I'm wrong but isn't rst/sphinx the only/best way to get Latex Math equations ?

[MitchellAcoustics]

Looks like mkdocs-material has support for Latex equations via MathJax or Katex - https://squidfunk.github.io/mkdocs-material/reference/math/.

Okay, I'll keep it in mind if I decide to dive into the documentation more. But it's not the most important thing, so probably not a priority.

[Nitnelav]

Yeah not the priority for sure, but I'll support the endeavor if you go for it :)