Repository navigation
Rework getting-started.rst and README.rst for a newcomer; move the README's dated figures to decisions/readme-figures - #1417
Merged
Merged
Conversation
…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>
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 newdocs/design/decisions/readme-figures.mdwith its index line indocs/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.
suggest.rst's thresholdssuggest-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 "Whatsuggestdecides".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: onlysuggest.rststates them now.ambiguities→parser-guesses; the list; a pack; aPolicyfield or aLexiconedit), the issue link, and a "see whether the parser had to guess at a name" row in the table. The intro points at it.docs/migrate.rst"Finding the sites" (now linked by anchor): a read of the sharedCONSTANTS, a read of aLexiconset field, and the imports that section lists.locales.available()). Every example line is kept.zh, Japanese byjawith a segmenter (the extra); language conventions are packs, linkinglocales. Agrees witheast-asian.rst's table.csv.readerwarning before any exampleParsercloses "Parse one name"; thesuggestexample gains a loop over the list withsuggestion.parser; the iterator caveat follows it.consistent, a result having no truth value (if matcher.check(a, b):raisesTypeError). 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
suggestandmatchingexamples 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, andgetting-started.rst's opening is about East Asian order, so that page is left alone.python -m doctest README.rstand 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.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):
ESReported, 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:suggest.rstundersuggest-patronymics,suggest-initials,suggest-capitals;suggest-deciding;Zhang Wei, PhD)": cut,suggest-evidence;suggest-evidence;suggest-evidence. Both bylines doctest lines are kept;:ref:toeast-asian-namesin the install paragraph: replaced bysplitting-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
suggest.rstworker, not changed here: master'sgetting-started.rstgave 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 leavestotal);suggest.rstsays "the names that cast a vote", which is looser. After this PR onlysuggest.rststates it.Checks
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).:ref:ingetting-started.rstresolves to a label on master; everynameparser.readthedocs.io/en/latest/…URL in the README has its page, andmigrate.html#finding-the-sitesits anchor, in the built HTML. The README has no Sphinx roles.grep -rn 'README' tests/ tools/: the only test readingREADME.rst's text istests/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:after:
Reviews
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:suggeston the pack's parser, against the page's own "Choose the language first".migrate.rstlists four bullets: the count is gone.parser-guesses.locales.ja_segmenter()ships.Kept against its style note: "Where it declines" still leads with "set it yourself", as the critique decided.
design-docs-reviewerondecisions/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.pr-review-toolkit:code-reviewer. Three defects the fix introduced, fixed in the head commit: "cz-candidatesholds 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,denames 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