More tolerant docstring parser

[PicoCentauri]

Our current docstring parser located at

https://github.com/MDAnalysis/mdacli/blob/78fa3f2fff31fb7f9acf71ee8811ab902369e947/src/mdacli/utils.py#L163

returns a dictionary of the the docstring. It works but it is not as flexible and tolerant as the sphinx/napoleon implementation. Especially we have problems with the separator between a parameter name and its type; usually denoted by name : type. A different notation can not be parsed since we use a hardcoded split

https://github.com/MDAnalysis/mdacli/blob/78fa3f2fff31fb7f9acf71ee8811ab902369e947/src/mdacli/utils.py#L230-L232

Improvements with using a regex did also not succeed. If possible we should incorporate the sphinx parser or at least get some ideas from their implementation.

[joaomcteixeira]

I had committed a re.split in the PR, then we rejected it. Won't that help? Do you wan to go beyond #23 ?

[joaomcteixeira]

Example by @PicoCentauri

"""
    Attributes
    ----------
    dim_fac : int
        Dimensionality :math:`d` of the MSD.
    results.timeseries : :class:`numpy.ndarray`
        The averaged MSD over all the particles with respect to lag-time.
    results.msds_by_particle : :class:`numpy.ndarray`
        The MSD of each individual particle with respect to lag-time.
    ag : :class:`AtomGroup`
        The :class:`AtomGroup` resulting from your selection
    n_frames : int
        Number of frames included in the analysis.
    n_particles : int
        Number of particles MSD was calculated over.


    .. versionadded:: 2.0.0
"""

[joaomcteixeira]

"""
    Parameters
    ----------
    universe : Universe
        Universe object
    select : str
        Selection string to evaluate its angular distribution ['byres name OH2']
    bins : int (optional)
        Number of bins to create the histogram by means of :func:`numpy.histogram`
    axis : {'x', 'y', 'z'} (optional)
        Axis to create angle with the vector (HH, OH or dipole) and calculate
        cosine theta ['z'].


    .. versionadded:: 0.11.0

    .. versionchanged:: 1.0.0
       Changed `selection` keyword to `select`
"""

[joaomcteixeira]

try again numpydocs. where docstrings updated in mda since #2 ?

[PicoCentauri]

I just checked the numpydocs parser and they are still not able to parse docstrings without surrounding spaces...

[joaomcteixeira]

Yes,

I tried the other day and I saw it was also a bit of a mess. I think we (ok me :stuck_out_tongue: ) should write this more general parser, that is also compatible with the synphx parsing and than create tests on the side of MDAnalysis to enforce new Analysis classes follow these guidelines.