Skip to content

Rework getting-started.rst and README.rst for a newcomer; move the README's dated figures to decisions/readme-figures - #1417

Merged
derek73 merged 5 commits into
masterfrom
docs/front-door
Nov 16, 2026
Merged

derek73 merged 5 commits into
masterfrom
docs/front-door

Conversation

@derek73

@derek73 derek73 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Reworks the two front-door pages for a reader who has never used the library, per the reader critique of both (docs/AGENTS.md, "A reader critique before release"). Docs only: no code, test or vocabulary change.

Files: docs/getting-started.rst, README.rst, and, as the one sanctioned exception to "two files only", a new docs/design/decisions/readme-figures.md with its index line in docs/design/decisions/README.md (item 5 below: the README's dated figures had no dated record in the repository).

The critique's twelve items

All twelve are done; none skipped.

# Item What changed
1 getting-started: the "four settings" list carried suggest.rst's thresholds Each bullet is a name, one clause and links (suggest-deciding, suggest-patronymics, suggest-initials, suggest-capitals); the lead-in says each is decided "only where enough of the list's names carry its evidence". Qualifiers kept so no clause widens: "only on a base that reads given names first", "capitals of four letters or more". New subheading "What suggest decides".
2 "Where it declines" was reference fine print Leads with "Where you know the order … set it yourself"; one paragraph and the declining doctest; links suggest-limits. Both bylines doctest lines stay, under one sentence giving their own reason (bylines vote only where enough of a list's names end in initials). The "two thirds", one-word, comma and 60% sentences are cut: only suggest.rst states them now.
3 The scan's one hit (147 words) Three paragraphs: the capitals count; the four votes and the double count; the name with no evidence and the name that disagrees.
4 No "a name was read wrong" route New section "When a name is read wrong": four ordered steps (ambiguities → parser-guesses; the list; a pack; a Policy field or a Lexicon edit), the issue link, and a "see whether the parser had to guess at a name" row in the table. The intro points at it.
5 README: dated measurements and CI detail See "The README's figures" below.
6 README: migration below the measurements "Coming from 1.x or 2.x" now follows "Learn more", above the figures.
7 README: the unparseable migration sentence Three numbered steps. The exceptions are the same three, checked against docs/migrate.rst "Finding the sites" (now linked by anchor): a read of the shared CONSTANTS, a read of a Lexicon set field, and the imports that section lists.
8 README: the announcement Split: the 3.1 features as two bullets; a one-line "Upgrading from 1.x or 2.x?" pointer; the issue link moved to "When a reading is wrong for your data".
9 README: "More shapes the parser reads" Now a section with three bold leads: titles, suffixes and commas; other scripts (the CJK paragraph from the top of the page moved here); language packs (the pack paragraph from "Getting started" moved here, beside locales.available()). Every example line is kept.
10 getting-started: non-English data Two short paragraphs after install: read by position, never guesses the language; CJK script family-first without configuration, save katakana alone; unspaced Korean by default, Chinese by zh, Japanese by ja with a segmenter (the extra); language conventions are packs, linking locales. Agrees with east-asian.rst's table.
11 getting-started: csv.reader warning before any example A loop over a column with one Parser closes "Parse one name"; the suggest example gains a loop over the list with suggestion.parser; the iterator caveat follows it.
12 getting-started: the closing matching paragraph Two paragraphs; the second leads "It is not proof of the same person". The first now says to read consistent, a result having no truth value (if matcher.check(a, b): raises TypeError). The examples already read .consistent.

Left as they were, as the critique asked: the "Where to go next" table (one row added), "Choose the language first", and the suggest and matching examples the two pages share (unchanged on both, so they still agree).

Added after the reviews: a Thai glued title on the README

Asked for by the maintainer through the coordinator. The "Other scripts" block gains one doctest, parse("นายสมชาย ใจดี") → title นาย, given สมชาย, family ใจดี, with a sentence in its lead (Thai writes a salutation joined to the given name with no space, and the parser splits it off) and a sentence in the 3.1 announcement. Run against the tree (สมชาย ใจดี alone reads given สมชาย, family ใจดี; นางสาวสมหญิง ใจดี and อาจารย์สมชาย ใจดี split the same way), worded as the release log's 3.1 bullet on a glued Thai salutation is. No user page has a Thai section to link, and getting-started.rst's opening is about East Asian order, so that page is left alone. python -m doctest README.rst and PyPI's renderer pass with the Thai text. This commit was not sent to a reviewer.

After the coordinator's review

  • docs/release_log.rst (a third exception to "two files", one sentence, asked for by the coordinator): the 3.1.0 bullet on Thai academic titles said a title glued to the name with no full stop (อาจารย์สุดา) still reads as part of the given name. False on master since Thai honorifics are glued to the given name (นายสมชาย → given "นายสมชาย") #317: parse("อาจารย์สุดา ใจดี") gives title อาจารย์, given สุดา. It now says only a title written short and glued with no full stop does (parse("ดรสุดา ใจดี") gives given ดรสุดา), as the bullet above it says.
  • README: the Thai sentence no longer follows the pointer to the East Asian names page, which does not cover Thai, and says it needs no configuration.
  • README: master's sentence "Most of what the default misses is a convention rather than a misreading." is kept, in the "Choosing the language" bullet.

The README's figures (item 5)

None of the README's dated figures had a full dated record in the repository: the accuracy report of 2026-11-05 was never committed, and the speed and test figures stood only in PR #1147's body. So this PR adds docs/design/decisions/readme-figures.md, which holds (a) the dated text the README carried, harvested with its recipes from the README and the bodies of #1106 and #1147, and (b) a re-take of every figure on this tree, dated 2026-11-15, with the command for each. The README links it.

Each rounded figure beside its record (2026-11-15 column of that file; master at dfd9b77, py3.11):

README says Measured 2026-11-15 Was on the README
US patent inventors: about 95% 623,153 of 657,991, 94.71% 94.7%
…outside Spanish- and Portuguese-speaking countries: about 98% 585,688 of 597,174, 98.08% 98.0%
UK company filings: about 97% 1,006,946 of 1,039,149, 96.90% 96.8%
Czech candidates: about 97% 165,003 of 170,181, 96.96% 97.0%
ORCID Spain: about half → about 97% under ES 49.54% → 96.70% of 19,510 49.5% → 96.7%
Argentine patent inventors: about 94%, 86%, 93% 93.84 / 86.18 / 92.73% of 3,343 93.8 / 86.2 / 92.7%
US patent inventors are "at most 20,000 from each country" the corpus's cap (202 countries, 23 at it) unstated
a parse: roughly a tenth of a millisecond on a recent laptop 104.8 µs at best; 107 to 218 µs in the other runs, on a machine other sessions were loading about 90 µs (2026-11-07)
first parser of a language choice: tens of milliseconds 74 to 77 ms 37 to 51 ms (#1147)
another choice after it: under ten; the same choice again: about one millisecond 8.5 to 8.7 ms; 1.1 to 1.2 ms "a few milliseconds"; "about 1 ms"
tens of thousands of tests 48,854 collected 40,256

Reported, not acted on: the first build of a language choice costs about twice what #1147 measured on the 3.0 tree (74 to 77 ms against 37 to 51), more than the load explains; "tens of milliseconds" still holds. No timing here was taken on a quiet machine.

Gone from the README on purpose, each recorded in the decisions file: the record counts, Mexico's figure (33.6% → 96.9%), the Czech pack's 97.5%, "some 11,000 names a second" and the timing recipe, the scaling tests' "32 costly input shapes" (35 today), the CI jobs and per-job test counts, and the snapshot and deviates: paragraphs with their two links.

Nothing dropped without a decision

Literals, numbers, roles and links were diffed by script between master's pages and the new ones.

getting-started.rst, gone:

  • the thresholds in the four bullets ("at least five names, and more than four in five", "at least two names, and at least half", "at least two names, and more than two thirds"): cut, stated by suggest.rst under suggest-patronymics, suggest-initials, suggest-capitals;
  • "An order needs at least two names voting for it, more than two thirds of the names whose own order votes do not contradict each other": cut, suggest-deciding;
  • "A name of one word casts none, nor does a name with a comma, unless only post-nominals follow it (Zhang Wei, PhD)": cut, suggest-evidence;
  • "at least three names … at least 60% of the list's names": cut, suggest-evidence;
  • the sentence on what leaves the bylines count (a name a comma leaves out, a name of nothing but titles): cut, suggest-evidence. Both bylines doctest lines are kept;
  • :ref: to east-asian-names in the install paragraph: replaced by splitting-unspaced-names; the table still links the page.

README.rst, gone: the figures listed above, "unless a parse has already loaded it" (the reading index; in the record), and nothing else. Every example line, the migration paragraph's facts and the licence section are unchanged.

Found on master

  • No statement on either page was found false against the tree; one release-log sentence was (above).
  • Stale dated counts on the README, now off it: "40,256 tests" (48,854 today), "32 costly input shapes" (35), UK filings "96.8%" (96.90% on this tree).
  • For the suggest.rst worker, not changed here: master's getting-started.rst gave the order share's denominator as "the names whose own order votes do not contradict each other", which is what _suggest.py's tally does (a name with votes for both ends is counted as contested and leaves total); suggest.rst says "the names that cast a vote", which is looser. After this PR only suggest.rst states it.

Checks

  • Every example and stated behaviour added, moved or reworded was run against the tree before it was written.
  • uv run sphinx-build -q -E -b html docs <tmp> and -b doctest docs <tmp>: no output.
  • uv run python -W error -m doctest README.rst: passes.
  • uv run --with readme_renderer python -m readme_renderer README.rst: exit 0, no docutils warning (it caught a heading underline one character short, fixed before the first commit).
  • Links: every :ref: in getting-started.rst resolves to a label on master; every nameparser.readthedocs.io/en/latest/… URL in the README has its page, and migrate.html#finding-the-sites its anchor, in the built HTML. The README has no Sphinx roles.
  • grep -rn 'README' tests/ tools/: the only test reading README.rst's text is tests/v2/test_licensing.py (the License section, untouched): 7 passed.
  • tests/v2/test_design_docs.py, test_doc_citations.py, test_rules_doc.py: pass with the new decisions file.

uv run python tools/docs_scan.py getting-started.rst, before:

getting-started.rst      1  1 PARA
docs/getting-started.rst:95: PARA     147 words: Each setting counts its names for and against the value the suggested ...

after:

getting-started.rst      0

Reviews

  1. Round 1 on ea03a9e, the pages: pr-review-toolkit:code-reviewer, given master's pages and the new ones and told to run every stated behaviour. No doctest or stated behaviour was false; eight prose defects, all fixed in 991f529:
    • README "tens of milliseconds, once in a process" read as a cost paid once, leaving "reuse it" without its reason (a rebuild costs about ten parses).
    • getting-started's read-wrong steps put "let the list choose" before "choose the language" without saying to call suggest on the pack's parser, against the page's own "Choose the language first".
    • "So a short list … of bylines" gave the wrong reason (no byline votes at all in a list of two), and the three-name edge was on no page: restored.
    • README "three exceptions" where migrate.rst lists four bullets: the count is gone.
    • The new table row "see why a name was read the way it was" was wider than parser-guesses.
    • "after folding case, periods, commas and spacing" had been dropped from the accuracy intro.
    • "A pack costs" generalised the Spanish pack's cost.
    • "a segmenter, which the extra installs": the extra installs namedivider; locales.ja_segmenter() ships.
      Kept against its style note: "Where it declines" still leads with "set it yourself", as the critique decided.
  2. Round 1 on ea03a9e, the record: design-docs-reviewer on decisions/readme-figures.md. No transcription or arithmetic error; seven findings, all fixed in 991f529: a "Per the PR body" paragraph that held reconstructed commands and an inferred reason (now README: show 3.0's two family names, views and packs in the examples #1106's words quoted, the rest marked as added at harvest); two headlines their entries contradicted; the corpora's sampling unstated (PatentsView and ORCID capped at 20,000 a country, PSC 1 in 8), which also put "at most 20,000 from each country" on the README; the es/pt count's make-up; ORCID's data date; the list of what the README no longer says.
  3. Round 2 on 991f529, the fix commit: pr-review-toolkit:code-reviewer. Three defects the fix introduced, fixed in the head commit: "cz-candidates holds every candidate" (a record is a candidate's boxes in one election, 170,181 of 201,981 candidates); README "each word says which language's vocabulary read it" (most words name none, de names eight); the PSC sample is of distinct filed names. Its timings also showed the first build slower than Add a Speed and testing section to the README #1147's, so the build times were re-taken and recorded, and "a few" became "under ten".

Review aspects not run: tests, types, error handling and comments do not apply to a docs-only change.

🤖 Generated with Claude Code

…ine print behind links, a "read wrong" route, rounded undated figures on the README with the dated record in decisions/readme-figures

getting-started.rst: the four settings suggest decides are a name, a
clause and a link each; "Where it declines" leads with "set it
yourself"; the long evidence paragraph is three; a loop over a column
of names; what the default does for names in other scripts; a "When a
name is read wrong" section; the matching fine print split in two.

README.rst: the announcement split; "More shapes the parser reads"
under three leads (titles, suffixes and commas; other scripts; language
packs); the migration steps numbered and moved above the figures; the
accuracy and speed figures rounded and undated, linking the new
docs/design/decisions/readme-figures.md, which holds the dated text the
README carried and a re-take of every figure on this tree.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@derek73 derek73 added the docs Documentation fixes and updates label Nov 16, 2026
@derek73 derek73 self-assigned this Nov 16, 2026
derek73 and others added 4 commits November 15, 2026 21:58
…ures record

README: the build cost no longer reads as paid once (another choice a
few ms, the same choice again about one); the migration steps name no
count of exceptions; the agreement is "after folding case, periods,
commas and spacing" again; the patent population says its per-country
cap; "The Spanish pack costs", not "A pack".

getting-started: the read-wrong steps say to call suggest on the pack's
parser; the bylines example gives its own reason and its three-name
edge is back; the table row says "had to guess"; the ja extra is what
ja_segmenter() needs, not what installs it.

decisions/readme-figures: the #1106 entry quotes that PR's words and
marks what was added at harvest; its headline and the 2026-11-15 one
say what each entry holds; each corpus's sampling, ORCID's data date,
the outside-es/pt count's make-up and the dropped build figures are
stated.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ings re-taken

README: a word the vocabulary read says which languages' vocabulary it
came from (most words name none); another choice of languages costs
"under ten" milliseconds, which holds for both measurements.

decisions/readme-figures: a cz-candidates record is a candidate's boxes
in one election, not every candidate; the PSC sample is of distinct
filed names; the README's one per-country figure is its own Standing
line dated 2026-11-15; the parser-build times are re-taken (the first
build of a language choice costs more on this tree than on 3.0's) and
the headline says so.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…f, new in 3.1

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…eeds no configuration, and the misses are conventions

release_log: a spelled-out Thai title glued to the name splits off
since #317 (parse("อาจารย์สุดา ใจดี") gives title อาจารย์); only a title
written short and glued with no full stop (ดรสุดา) stays in the given
name. README: the Thai sentence no longer follows a pointer to a page
that does not cover Thai, and master's sentence "Most of what the
default misses is a convention rather than a misreading" is back.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@derek73
derek73 merged commit b46f786 into master Nov 16, 2026
14 checks passed
@derek73
derek73 deleted the docs/front-door branch November 16, 2026 06:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation fixes and updates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant