[WIP] Parsing docstrings too.

[JulienPalard]

closes #141

[JulienPalard]

Here how it goes on friends projects:

tests/fixtures/friends//sympy/doc/ext/docscrape.py:448: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//pandas/doc/source/reference/aliases.rst:68: Extra backtick in role: ':py:attr:`ordered``' (role-with-extra-backtick)
tests/fixtures/friends//pandas/doc/source/reference/aliases.rst:92: Extra backtick in role: ':meth:`rank``' (role-with-extra-backtick)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:51: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:57: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:63: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:71: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:83: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:95: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:105: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:183: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:191: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:205: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:345: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:357: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:359: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:361: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:363: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:365: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//peps/peps/pep-0418/clockutils.py:367: trailing whitespace (trailing-whitespace)
tests/fixtures/friends//cpython/Doc/includes/ndiff.py:6: Line ends with dangling hyphen (dangling-hyphen)

So there's one false positive in cpython, which is expected as cpython does not use rst in their docstring.

I think this check could be opt-in, as using rst in docstrings may not be the default?

Like sphinx-lint --docstrings ?

[PicoCentauri]

Yes it worked nicely. I think one could either do an opt in or an opt out with

sphinx-lint --no-docstrings

I found a couple of false positives as well, but very good start. I will list them below

I think one should not check for general Python strings or code and only check if they are in a real docstring. Everything else will not be rendered anyway with sphinx.

It is probably not enough to grep only text between tripe quotes because there are also attribute annotations that will be rendered.

---

tests/core/test_base.py:1024: default role used (hint: for inline literals, use double backticks) (default-role)

for a function like

class TestPlanarBaseChilds:
    """Tests for the AnalayseBase child classes."""

    ignored_parameters = ["atomgroup", "wrap_compound"]

    @pytest.mark.parametrize("Member", find_cls_members(AnalysisBase, ["maicos"]))
    def test_parameters(self, Member):
        """Test if AnalysisBase paramaters exist in all modules."""
        base_sig = inspect.signature(AnalysisBase)
        mod_sig = inspect.signature(Member)

        for param in base_sig.parameters.values():
            if param.name in self.ignored_parameters:
                continue

            try:
                mod_sig.parameters[param.name]
            except KeyError as err:
                raise KeyError(f"{param.name} is not a parameter of {Member}!") from err

---

I just have a class docstring and get an error in the last line

/Users/philiploche/repos/maicos/maicos/examples/dielectrics/dielectric-profiles.py:19: default role used (hint: for inline literals, use double backticks) (default-role)

"""
Dielectric profile calculation
==============================

In the following example, we will show how to calculate the dielectric profiles as
described in :ref:`dielectric-explanations`.

Before producing trajectories to calculate dielectric profiles, you will need to
consider which information you will need and thus need to print out. The dielectric
profile calculators need unwrapped positions and charges of **all** charged atoms in the
system. Unwrapped refers to the fact that you will need either "repaired" molecules
(which in GROMACS ``trjconv`` with the ``-pbc mol`` option can do for you) or you will
"""

[JulienPalard]

I added tests (cf. last commit) with your codes and I was not able to reproduce your issues.

Can you provide tests reproducing your findings?

[JulienPalard]

I think one should not check for general Python strings or code and only check if they are in a real docstring. Everything else will not be rendered anyway with sphinx.

That's what's this PR does: only docstrings.

[PicoCentauri]

Yes, sorry I was confused because I got an error for a docstring that has an example code block

"""
>>> a = 1 # refers to the value of `a`
"""

But I will add a test.

[PicoCentauri]

I updated the one docstring with valid inline comments that should be valid. I am not allowed to push to your branch. I pasted my changes below:

class Youpi:
    """Dielectric profile calculation
    ==============================

    In the following example, we will show how to calculate the dielectric profiles as
    described in :ref:`dielectric-explanations`.

    Before producing trajectories to calculate dielectric profiles, you will need to
    consider which information you will need and thus need to print out. The dielectric
    profile calculators need unwrapped positions and charges of **all** charged atoms in
    the system. Unwrapped refers to the fact that you will need either "repaired"
    molecules (which in GROMACS ``trjconv`` with the ``-pbc mol`` option can do for you)
    or you will

    Examples are

    .. code-block:: python
    
        a = 1  # refers to the value of `a`

    or

    >>> b = 2  # refers to the value of `b`

    """