Adding python 3.10 documentation

[argerlt]

Is your feature request related to a problem? Please describe.
Hello, first time py4dstem poster and fairly new 4DSTEM user.

Question for the devs: the dynamical simulation notebooks have been hugely helpful for me, both in terms of my research and also just learning about Bloch waves. However, the process.diffraction.crystal functions have docstrings that don't follow the normal numpy-style standards, which makes querying them difficult. See the following screenshot for an example:

Note how several of the inputs get incorrectly shoved into the discriptions of args.

Will anyone care if I submit a PR cleaning these up? Not changing any calculations, just making all the type hints and parameter descriptions and whatnot pep-compliant, so they render properly in the documentation.

I wanted to check before starting because occasionally these atypical docstrings are intentionally designed a certain way to render properly in some third party solution.

Describe the solution you'd like
Someone to give me the thumbs up to change things

Describe alternatives you've considered
reading the raw code in the repo.

Additional context
N/A.

[argerlt]

Looking back, "cleaning these up" is far too hand-wavy for a PR about precision documentation.

I'm specifically talking about changing functions like this:

    def from_unitcell_parameters(
        latt_params,
        elements,
        positions,
        space_group=None,
        lattice_type="cubic",
        from_cartesian=False,
        conventional_standard_structure=True,
    ):

        """
        Create a Crystal using pymatgen to generate unit cell manually from user inputs

        Args:
                latt_params:         (list of floats) list of lattice parameters. For example, for cubic: latt_params = [a],
                                     for hexagonal: latt_params = [a, c], for monoclinic: latt_params = [a,b,c,beta],
                                     and in general: latt_params = [a,b,c,alpha,beta,gamma]
                elements:            (list of strings) list of elements, for example for SnS: elements = ["Sn", "S"]
                positions:           (list) list of (x,y,z) positions for each element present in the elements, default: fractional coord
                space_group:         (optional) (string or int) space group of the crystal system, if specified, unit cell will be created using
                                     pymatgen Structure.from_spacegroup function
                lattice_type:        (string) type of crystal family: cubic, hexagonal, triclinic etc; default: 'cubic'
                from_cartesian:      (bool) if True, positions will be considered as cartesian, default: False
                conventional_standard_structure: (bool) if True, conventional standard unit cell will be returned
                                     instead of the primitive unit cell pymatgen returns
        Returns:
                Crystal object

        """

to this:

    def from_unitcell_parameters(
        latt_params: list[float],
        elements: list[str],
        positions: list[list[float], list[float], list[float]] | None,
        space_group: str | int | None = None,
        lattice_type: Literal[
            "cubic", "hexagonal", "triclinic", "orthogonal"
        ] = "cubic",
        from_cartesian: bool=False,
        conventional_standard_structure: bool=True,
    ):
        """Create a Crystal using pymatgen to generate unit cell
        manually from user inputs
        
        Parameters
        ----------
        lat_params
            List of lattice parameters. For example,
                - cubic: latt_params = [a]
                - hexagonal: latt_params = [a, c]
                - monoclinic: latt_params = [a,b,c,beta]
                - general: latt_params = [a,b,c,alpha,beta,gamma]
        elements
            List of elements. For example:
                SnS: elements = ["Sn", "S"]
        positions
            list of (x,y,z) positions for each element present in the
            elements. default is fractional coordinates
        space_group
            Space group of the crystal system. If specified, the unit
            cell will be created using :class:pymatgen.Structure.from_spacegroup
        lattice_type
            Type of crystal family. the choices are cubic (default),
            hexagonal, triclinic, orthogonal,  etc
        from_cartesian
            If True, positions will be considered as cartesian. default is
            False
        conventional_standard_structure
            If True (default), conventional standard unit cell will be returned
            instead of the primitive unit cell pymatgen returns

        Returns
        -------
        Crystal object
        """

which then looks like this in type hints:

regardless though, I'll submit a PR and go from there.

[sezelt]

I don't think we were following any particular pattern when writing those docstrings, so feel free to rewrite them in a more standardized way.

[bsavitzky]

Hi @argerlt - a PR like this would be great. As Steve said, please do feel free to overhaul these. I'll just add a small modification to the docstring style you've written above, to include the type in the same line as the argument name after a colon, like this:

"""
(...text...)

Parameters
------------
x : float
    the first parameter
y : list of strings
    the second parameter
z : array
    the third parameter
"""

See, e.g. here

[argerlt]

@bsavitzky sounds good. Some projects have been dropping the type hints in the parameter section since it's redundant with the type hints in the function inputs, and doubling documentation doubles the chances for errors.

But, both numpy 2.3.1 and numpydoc 1.9.0 still include both types of hints, and I've yet to see a PEP standard encouraging the practice either way. I think it's purely preference, and sounds like the preference is to have both in py4DSTEM, so easy change.

[bsavitzky]

Great. Its completely acceptable either way in py4DSTEM - either one would be better than what these methods have now!