Code snippet docstring formatting

[deppen8]

We have a number of Python code snippets that include a docstring where each new line starts with *. I think "canonical" Python formatting would tell us to use a one-line triple-quoted description.

So this:

"""
 * Python libraries for learning and performing image processing.
 *
"""
import numpy as np
import matplotlib.pyplot as plt
import ipympl
import imageio.v3 as iio
import skimage

Would become this:

"""Python libraries for learning and performing image processing."""

import numpy as np
import matplotlib.pyplot as plt
import ipympl
import imageio.v3 as iio
import skimage

Thoughts?

[bobturneruk]

Python has several different docstring formats - sorry for the dated reference. I don't think there's a canonical format, but happy to be corrected!

I think here the docstrings are being used as comments so it's probably not critical that they are in a particular format, as long as they are consistent, other than to model good practise.

[deppen8]

I'm thinking here of PEP 257, https://peps.python.org/pep-0257/#one-line-docstrings

[bobturneruk]

Looks like your proposal is the best way to do things in this situation.

[tobyhodges]

If you can find time to prepare a PR, @deppen8 , I'll be happy to review.