[rr-]

Google and Numpydoc now recognise every section listed in the Sphinx napoleon docs:

• Keyword Args / Keyword Arguments are keyword params (Kind.KEYWORD), in both styles.
• Google only: Other Parameters and Receive / Receives are other and received params. Warns / Warn give raises of Kind.WARNS. Raise, Return and Yield are read like their plural forms.
• These are free-text sections, each giving a text meta with its title set: Note(s), Warning(s), See Also, References, Todo, Methods, Attention, Caution, Danger, Error, Hint, Important and Tip. Numpydoc already had the first four, and its text metas now carry their title as well.
• Google Deprecated: gives a DocstringDeprecated. If the body starts with a version, that becomes the version: 1.2.0 Use other instead. gives version 1.2.0 and description Use other instead.

Compose writes keyword, other and received params, and warns, into sections of their own. In Google they used to go under Args: / Raises:, and in Numpydoc keyword params went under Parameters, so they read back as the wrong kind. Google text sections are written under their title and no longer under a name derived from the key. For example, see_also used to come out as Seealso:.

Google compose also indents a summary that would otherwise read as a title, such as Note:, when a later line is unindented. One generated docstring now round trips because of this, so (1856, GOOGLE) is removed from GENERATED_EXCLUSIONS. No other exclusions changed.

With roughly 40 titles in the regex, Google parse got 65% slower and Numpydoc 23% slower. The cause was a capture group around every title, which stops the regex engine from skipping an alternative after its first letter. Google now uses one group for the title. Numpydoc uses none for headers that begin with their title, and reads the title from the first line of the match. Compose's nested functions on 3.8 now use annotation aliases defined once at module level.

Thanks to @BrianPugh, whose #108 asked for several of these sections.

Case diffs

• 147 Numpydoc case files only gain a title: line on their text metas (Notes, See Also, Warnings, ...).
• convert/numpydoc-other-and-received-params and convert/rest-params: other, received and keyword params are composed to Google under Other Parameters:, Receives: and Keyword Args: instead of Args:. Numpydoc puts keyword params under Keyword Arguments.
• corpus/pydantic/pydantic.fields.Field: Note: was long description and is now a notes text meta.
• corpus/numpy/..._NestedSequence: its Warning heading keeps that title, so compose writes Warning instead of Warnings.
• New: google/napoleon_sections_01 to _03, google/summary_title_01 and numpydoc/napoleon_sections_01.

Parity against origin/main

origin	differ	compose only	parses only in base
case	144 of 1552	139	0
stdlib	26 of 7631	1	3
generated	3985 of 20000	3250	0

tools/parity.py also reports 13 generated inputs that parse only in the tree.

Most of the compose-only differences come from three things: the title that compose now writes (See Also: instead of Seealso:), the new keyword/other/received/warns sections, and the indented title-like summary when composing to Google from another style. The stdlib parse differences are docstrings where a line like Methods:, References:, Notes:, Note: or Example: now starts a section. The three that parse only in base are argparse's Action, FileType and ArgumentParser: their Keyword Arguments: items look like - prog -- text, which have no colon, so a Google parse now raises ParseError where it used to keep the text. Napoleon reads those the same way. Auto-detection still picks another style for them.

Bench

Python 3.8, ratios between 0.76 and 1.06. The worst is Google parse at 1.06, mostly due to case-insensitive matching. Numpydoc parse is 0.84 and Google compose 0.78.

Not done

• A Numpydoc Deprecated heading with an underline. Numpydoc already reads .. deprecated:: version, the numpydoc form, and a Deprecated heading would clash with it once titles match in any case.
• Methods is free text. Napoleon reads it as name: description fields, but no Kind exists for methods.