Use Taylor Morgan, a name with no evidence, in the group suggester's headline example - #1362

The group suggester's headline example opened with Smith Mary, which votes for itself (Mary is in the given-name table), so it read as if the parser recognized the name. The example now opens with Taylor Morgan: both words are ordinary given names and ordinary surnames, neither is in the suggester's tables, and it is read family first only because the rest of the list is. The headline list is also written in one order throughout, as a list from one source is, so Mary Smith (given first) is replaced by Garcia Emily, which votes by the given name at the end.

Changed examples (outputs taken from the tree)

Headline list in README.rst, docs/getting-started.rst, docs/suggest.rst and the 3.1 Parser.suggest() release-log bullet:

• before: ["Smith Mary", "Kim Minjun", "Wang Xiaoming", "Nguyen Anh", "Mary Smith"], which printed 4 for, 1 against, 0 no evidence with disagreeing (1): Mary Smith
• after: ["Taylor Morgan", "Kim Minjun", "Wang Xiaoming", "Nguyen Anh", "Garcia Emily"], which prints name_order FAMILY_FIRST 4 for, 0 against, 1 no evidence (surname 3, given-name FAMILY_FIRST 1) with no disagreeing line. parse("Taylor Morgan").given is 'Taylor', and the suggested parser reads it as 'Morgan'.

The prose after each printout names the roles: Kim, Wang and Nguyen vote by the romanized surname in front, and Garcia Emily by the common given name at the end. Taylor Morgan gives no evidence, and nothing in the name can confirm the reading it gets. The opening claim now says one name often cannot show its order.

Matching example in getting-started.rst: the registry is now Taylor Morgan + the three surnames. check(registry.parse("Taylor Morgan"), parse("M. Taylor")) is consistent, and with the default parser it is not.

New in docs/suggest.rst, each a doctest:

• A name that disagrees (label suggest-disagreeing, linked from getting-started): the headline list plus Emily Clark prints 4 for, 1 against, 1 no evidence and disagreeing (1): Emily Clark, and the suggested parser reads given 'Clark'.
• Evidence other than a surname: ["Parker Emma", "Reed Sophie", "Ellis Jordan"] gives PolicyPatch(name_order=FAMILY_FIRST), decided by the given names at the end. Ellis Jordan carries none and is read given 'Jordan'. This uses given names rather than capitals because a capitals Policy switch is in flight in another branch.
• No evidence: ["Taylor Morgan", "Jordan Casey", "Avery Quinn"] gives PolicyPatch().

The evidence list in suggest.rst and the release-log bullet now say a given name votes only if it is rarely a surname (Emily, not Taylor). Without that, the new no-evidence examples, which are built from common given names, would contradict them.

Checks

• sphinx-build -b doctest docs: 828 tests, 0 failures (822 on master)
• sphinx-build -W -b html docs: clean
• python -m doctest README.rst and readme_renderer: clean
• uv run pytest: 45962 passed, 38 skipped, 3 xfailed
• uv run mypy and uv run ruff check: clean

Review

A reviewer subagent worked in its own detached worktree and ran twice: on the first head, then on the head that rewrote the list in one order. Each time it ran every changed example and checked every sentence about who voted against the printed NameEvidence.

• First round: the evidence list said "a common given name", which the no-evidence examples contradict. "One name cannot show its order" overclaims next to Kim Minjun. Both are fixed.
• Second round: "a name written the other way round votes against" holds only for a name that carries evidence. The README still said "cannot", and the no-evidence sentence was clumsy. A note was also added that Garcia is not one of the surnames suggest reads. All are fixed.

Left out of scope: the TypeError message in nameparser/_suggest.py still offers parser.suggest(["Smith Mary", "Kim Minjun"]) as its example. That is library code.

🤖 Generated with Claude Code