Add a getting-started page, and lead README and the docs index with it - #1353

The second of the two PRs restructuring the user docs (the first, #1343, moved text only). This one writes the entry path: a getting-started page, the README and index leads that point to it, and the rewrites #1343 left for it.

Pages

suggest's claims on getting-started were checked against nameparser/_suggest.py and Parser.suggest's docstring: it decides name_order, patronymic_rules and initials_as_family, never a language, and keeps every other setting at the base's value. No accuracy figure is quoted on the page; it points to suggest.rst, which holds the measured table.

Removed doctests and claims

Doctests (>>> statements):

• usage.rst "Credentials that are also surnames": parse("Jack MA").suffix and parse("Jack Ma").family. Duplicated in customize.rst's section of the same title, which keeps both.
• usage.rst same section: parse("John Smith Ma").family. Moved to customize.rst's doctest beside the other two, where the prose already stated it.
• usage.rst "Titles that are also given names": parse("Dean of Students Jane Smith").title. Duplicated in customize.rst's titles-also-given-names doctest; usage keeps the phrase in prose and the title-or-name report.
• README.rst tour, each still shown elsewhere:
  • ES's two family names, surname1/surname2/generation and render on Juan Carlos García de la Vega: usage's surname1/surname2 doctests and languages.rst.
  • two_given_names reading Juan Carlos: policy.rst's two-given-names doctests.
  • Lady Heidenreich title by default, given under ES: locales.rst's doctest.
  • ES Lady Justice Jane Smith keeps the title: was prose only in locales.rst; added there as a doctest in this PR.
  • Strict ES reading Lady Justice Jane Smith with no title: not shown elsewhere with that name; locales.rst's strict-choice section shows a strict choice dropping English words with its own examples.
  • FAMILY_FIRST_GIVEN_LAST chaining Van Anh, and VI keeping Van a middle name: locales.rst and languages.rst (Nguyen Van Anh).

Claims (prose):

• usage's three-bullet summary of how a bare credential-or-surname is read (capitals, other cased spellings, the count "not counting a title or a nickname"): condensed to one sentence; the full rules stay in customize.rst's "Credentials that are also surnames", which already held them in more detail.
• locales' "East Asian names need no pack" detail (kanji with kana other than katakana alone; Korean surnames a closed census set shipped as default vocabulary; a Chinese surname list splitting Japanese names wrongly): cut to a pointer; east-asian.rst states each.
• usage's opening line (Python 3.11+, pip install nameparser): now on getting-started.
• usage's "Where next" lost its concepts, locales and migrate lines and "HumanName, which 3.0 removes"; getting-started's table and index.rst carry both links, and migrate.rst the fact.
• README's 3.0 announcement detail (Lexicon configured by reading, a name rendered in the order written, packs that choose languages): the release log's 3.0 entry holds each. Its list of what 3.0 removed (Constants, CONSTANTS, nameparser.util, the 1.x names of the word lists) and "2.8 is the last release that has them, and it warns at each use": README's "Coming from 1.x or 2.x" keeps Constants, CONSTANTS and the 2.8.2 warning; nameparser.util and the word-list names are in migrate.rst.
• The suggest example name: getting-started and README use Smith Mary / Mary Smith instead of the earlier example name, with the outputs re-run (the vote counts and the report are the same).

From #1343's "For the rewrite PR" list and the plan

Done: getting-started and its toctree entry; index.rst's lead links; README's 3.1 lead, quick start and East Asian link (now east-asian.html; usage.html#east-asian-names still resolves for released READMEs); both merges; the East Asian pointer; usage's "Where next" and retitle; customize's intro; "Contributing a pack" moved to contributing.rst; shapes.rst's "below".

Not done, and why:

• east-asian, matching, languages toward their targets: see the table.

• policy.rst's "see Vocabulary: Lexicon above" (policy.rst:667): policy.rst is being edited by another session this cycle. Reported to the coordinator.

Found outside this PR's files (not changed here)

• Parser.suggest turns initials_as_family on under a middle_as_family base, where its docstring (nameparser/_parser.py, "nor turns it on under a base reading names family first or folding every middle into the family") and docs/suggest.rst say it does not: Parser(policy=Policy(middle_as_family=True)).suggest(["Ram Bahadur B K", "Sita Kumari B K", "Hari K C", "Gita Devi B K"]).patch is PolicyPatch(initials_as_family=True), inert there. getting-started states what the code does (given-first base only).
• The earlier example name is still in docs/suggest.rst, docs/release_log.rst, the TypeError message in nameparser/_suggest.py (~line 1046, offered as code to paste) and the suggest tests.
• parse("金 민준") (mixed Han and Hangul) reads given 金, family 준: an odd reading the docs' "wholly in Han or Hangul" correctly leaves out, possibly worth an issue.
• Release-log :doc: links to labels: the release log is out of this PR's scope.
• Pointer placement in usage.rst: kept at the end of "Parse a name"; it reads fine there and the anchor stays on usage.html.

Anchors

New: getting-started (label and page), contributing-a-pack. Moved: "Contributing a pack to nameparser" from locales.html to contributing.html (its one in-page link is now a :ref:); usage's page-title anchor is now working-with-a-parsed-name. git grep for using-the-parser, Using the parser, contributing-a-pack, Contributing a pack and need no pack across docs/, README.rst, nameparser/, tests/, tools/ and every AGENTS.md finds no other reference (dated decisions entries excepted, as history). Root AGENTS.md's release-checklist docs line and docs/AGENTS.md's page list name getting-started.rst.

Proof

• uv run sphinx-build -b doctest docs <dir>: 822 tests, 0 failures (origin/master at 670b349: 788, 0 failures).
• uv run sphinx-build -W -b html docs <dir>: exits 0, prints nothing.
• README: python -m doctest README.rst passes; uv run --with readme_renderer python -m readme_renderer README.rst renders; every readthedocs.io/en/latest/<page>[#anchor] link in README resolves in the built HTML, and usage.html still holds id="east-asian-names" once.
• Re-run on the final commit: uv run pytest: 45,962 passed, 38 skipped, 3 xfailed; uv run pytest -n0 -m serial: 35 passed; uv run mypy: no issues; uv run ruff check: clean. tests/v2/test_es_given_names.py, test_doc_citations.py and test_doc_spellings.py pass.

Reviews

1. Docs review (fresh agent in its own worktree: ran every example, checked suggest/matching claims against the code, diffed removed sentences, read getting-started as a new user with a CSV). Found: usage's merged sentence said a Title-case Jack Ma reports nothing (it reports suffix-or-name); locales' and README's family-first sentence dropped the katakana-alone exception; "consistent" defined wider than check (opt-in outcomes, a name with no family); "a common given name" overstated (John casts no vote); the trailing-initial share's denominator; three omissions from the removed list; new-user gaps (no as_dict, suggest reads its iterable once, what to do with the disagreeing names, a one-word name matching nothing). All fixed.
2. Comment analysis (pr-review-toolkit) on the prose stating thresholds: the three shares stated against the wrong denominators (order, patronymic, trailing initials), the katakana claim, the initials_as_family bullet with no numbers, "the one optional extra" as a standing count. All fixed; thresholds confirmed equal to the tested constants in _suggest.py.
3. Review of the fix commit (fresh agent): the fix's initials_as_family condition followed the docstring, not the code (above); a comma name with only post-nominals does count toward the trailing-initial share; "two votes" should be two names; the disagreeing names may be misread, not are; usage's new "capitals settle it" is false of credentials written as words (KC, PC, DL); "and nothing else" (no dependencies) lost. All fixed in the last commit, each checked by running it.

🤖 Generated with Claude Code