Support abbreviations in property summaries

[Mr0grog]

This addresses one of the issues in #299, where sphinx.ext.autosummary supports a set of well-known abbreviations (e.g. “e.g.” 😉) in the first sentence of a docstring that is being summarized, but Numpydoc does not.

This only comes into play with properties that are listed in a class’s “Attributes” section. When Numpydoc tries to get the first sentence of a property’s docstring, it gets tripped up by abbreviations with periods and ends the summary after the abbreviation instead of at the actual end of the sentence:

class ExampleClass:
    """
    This is an example of how properties get formatted by numpydoc.

    Attributes
    ----------
    property_attribute
    """

    @property
    def property_attribute(self) -> int:
        """
        This attribute is actually a property (i.e. it's actually a function
        call under the hood).
        """
        return 5

Renders the summary of the property as ending with “i.e.”:

Open Questions/Caveats

My understanding from the discussion on #299 is that this logic is meant to largely match the behavior of autosummary (current logic in https://github.com/sphinx-doc/sphinx/blob/cc7c6f435ad37bb12264f8118c8461b230e6830c/sphinx/ext/autosummary/__init__.py#L553-L567), but the actual logic seems to have diverged a bit:

1. If there is no period in the opening stanza/paragraph, Autosummary takes the whole stanza, while Numpydoc takes only the first line. There are tests around this, so I assume it’s an intentional difference, and tried to call it out a little more clearly in the source.

2. Numpydoc’s previous implementation attempts to scan up to the first period and stop, while Autosummary splits all the candidate sentences into a list to work with. I don’t know if the difference was an intentional performance concern (what Numpydoc had should be faster and lower memory) or if it was drift over time or for some other reason.

   I rewrote the code using the same general structure and logic as Autosummary, so it should be easier update if/when things change there. But I can re-do this using re.finditer() if there are performance or other concerns.

[Mr0grog]

I added this example because the sentence-splitting regex used in sphinx.ext.autosummary was a little different, and caused some subtle issues here. This example was helpful in differentiating multiline behavior with and without a single period and multiple periods.