Split the usage, customize and locales docs into nine pages by task (move only) - #1343

The first of two PRs restructuring the user docs by task. This one only moves text. docs/usage.rst (12,680 words), docs/customize.rst (11,904) and docs/locales.rst (8,600) are split into nine pages, and docs/index.rst groups the toctree under four captions. Every sentence, example and heading is moved verbatim. Rewording, the getting-started page and the README lead are left to the second PR (list below).

Pages

Toctree captions: Reading names (usage, shapes, east-asian), Lists of names (suggest, matching), Configuring (customize, policy, locales, languages), Background and reference (concepts, modules, migrate, release_log, contributing). The three existing file names are kept, so the release log's :doc: links, the docstrings and README's absolute links still land on them.

Also removed

docs/resources.rst ("Naming Practices and Resources", 46 words) is deleted. It held eight external links, several out of date, and nothing linked to it but the toctree. A better page can come later. This is the one deliberate cut in the PR, and the word proof below covers only the three split pages.

Proof that nothing was lost

Cut from origin/master at 5a07205. The first two commits are what make the move mechanically checkable.

• fe691f4, the move. The split script's output, plus the two new page titles, their leads and the toctree. A moved heading's underline character changes only where its level changed. Compared with the three old pages on origin/master, with underline lines dropped from both sides and the four new title and lead lines dropped from the new side:

  • whitespace tokens: 33,057 old = 33,057 new, identical as multisets;
  • non-blank lines: 4,404 old = 4,404 new, identical as multisets, so no line was rewrapped.

  Sections from one source file land on their page in source order, and the script's ledger shows no order violations. Raw wc -w goes from 33,184 to 33,246; the difference of 62 is the two titles (7 words), their two underlines (2) and the two leads (53).

• 1de5d9e and the last commit, everything new. Their diff to the pages is exactly the new-text list below.

• Doctests. uv run sphinx-build -b doctest docs <dir> gives 776 tests, 0 failures; origin/master gives 771 tests, 0 failures. Sphinx counts each >>> statement, and the 5 extra are the five import lines added here. Counting >>>/... lines on both sides: 684 old, 689 new, the 5 imports added and none lost.

• HTML. uv run sphinx-build -W -b html docs <dir> exits 0 and prints nothing. The built usage.html holds id="east-asian-names" exactly once. Every .html# anchor in README.rst at v2.4.0, v2.8.0, v3.0.1 and HEAD resolves in the built pages: customize.html#configuring-by-reading, locales.html#reading-one-language-only and usage.html#east-asian-names.

• python -m doctest README.rst passes.

• uv run pytest and uv run pytest -n0 -m serial pass, as do uv run mypy and uv run ruff check, all re-run on the final commit. The clock-timed scaling checks in tests/v2/test_benchmark.py failed intermittently while the machine was loaded (load average 13-22, other sessions running suites). Untouched origin/master failed them under the same load, every re-run on a quieter machine passed, and the PR touches no library code.

New text, all of it

• Page titles and one-sentence leads, for the two pages that have no moved heading to serve as a title:

  • shapes: "Names the parser reads", with the lead "The input forms the parser reads without configuration: how a name is arranged, the words that attach to their neighbors, nicknames and maiden names, and titles it was not told about."
  • languages: "Notes by language", with the lead "What the shipped packs do for Czech, Slovak, Slovenian and Croatian names, Spanish and Portuguese titles, romanized Indic titles and Vietnamese names."

  The other four new pages take their moved heading as the title.

• Import lines, one visible line at the head of each page's first doctest, for names the page used to borrow from an earlier block on its old page:

  • shapes: from nameparser import parse
  • east-asian: from nameparser import Lexicon, parse
  • matching: from nameparser import Lexicon
  • policy: from nameparser import Lexicon
  • languages: from nameparser import Lexicon, Locale, Parser, locales, parse, parser_for

• Two labels: vocabulary-lexicon on Vocabulary: Lexicon and romanized-indic-titles on Romanized Indic titles.

• Eleven title links that no longer resolve on their page, rewritten as :ref:`<same link text> <label>` with the link text unchanged:

  • shapes → East Asian names (×2)
  • east-asian → When the parser had to guess
  • policy → Words that are also ordinary names, and Vocabulary: Lexicon
  • locales → Romanized Indic titles (×2), Spanish and Portuguese titles (×3), and Vietnamese names

• One in-page link retargeted: east-asian.rst's ":doc:`customize` covers turning any of these behaviors off" now links ``:ref:east-asian-defaults```, the section on the same page that holds those switches. Its sentence is unchanged. The other in-page :doc:` links still point at the right page.

• The pointer in usage.rst, where the East Asian section stood: a .. raw:: html <span id="east-asian-names"></span> and the line "East Asian names have a page of their own: :ref:east-asian-names." This keeps usage.html#east-asian-names, which every released README links to, landing on a pointer. The label itself moved with its section, since labels are global.

References repointed

• tests/v2/test_es_given_names.py checks the "1,000 Spanish given names" phrase in languages.rst and policy.rst, where it now lives.
• Comments that name a moved passage's page:
  • tests/v2/test_locales.py (2), tests/v2/test_parser.py (2), tests/v2/test_properties.py, tests/v2/test_order_correspondence.py and tests/v2/rules_doc.py;
  • tools/differential/shapes.py;
  • the docstring comment in nameparser/locales/ja.py;
  • docs/design/rules/W-scripts-and-writing-systems.md's pointer to the East Asian narrative.
• Release log: eight :doc:`customize` links whose subject moved now link the page it moved to. This changes the target only, never the entry's text.
  • Policy subjects go to :doc:`policy` (lines 472, 500, 510, 605, 606): the family-first order settling a particle, the maiden markers and the maiden delimiters.
  • East Asian switches go to :doc:`east-asian` (lines 565, 593, 599).
  • Lines 456 and 577 are about Lexicon edits and stay on customize.
• docs/conf.py's comment on member order names the policy.rst table.
• Root AGENTS.md:
  • the release checklist's docs-sweep line names shapes.rst beside usage.rst;
  • the suggester's figures are quoted in docs/suggest.rst;
  • "Titles you didn't configure" is in docs/shapes.rst;
  • the Japanese code-blocks are in east-asian.rst;
  • the doctest Gotcha says every .rst under docs/, not just two files.
• docs/AGENTS.md lists the nine pages and says the model Policy table is now policy.rst's.

Left as they are, on purpose:

• migrate.rst's "See :doc:customize for the full set of knobs" closes the "Vocabulary constants → Lexicon.words" section, so it still means the Lexicon page.
• tests/v2/pipeline/test_classify.py's Catalan/Polish recipe is still on customize.rst.
• Dated decisions entries, the RFC and nameparser/vocab/AGENTS.md mention the old pages as history, and history is kept.

For the rewrite PR

• Contributing a pack to nameparser. The outline moves it to contributing.rst. This PR's scope is the nine pages, so it stays at the end of locales.rst.
• Merges.
  • usage's "Credentials that are also surnames" with customize's section of the same title: the report stays in usage, the remedy in customize.
  • usage's "Titles that are also given names" with customize's titles-also-given-names, the same way.
• Cut to a pointer: locales' "East Asian names need no pack", since east-asian.rst's opening says the same.
• Rewrites.
  • usage's "Where next", which still lists only concepts, customize, locales and migrate.
  • customize's intro, as the order to try things in.
  • usage's retitle to "Working with a parsed name".
• New:
  • the getting-started page and its toctree entry;
  • index.rst's lead links to suggest and matching;
  • README's 3.1 announcement and quick start, pointing its East Asian link at east-asian.html.
• Direction words that now cross pages: shapes.rst "under East Asian names below" and policy.rst "see Vocabulary: Lexicon above" point at sections now on another page.
• Release-log links to labels: the eight retargeted :doc: links could point at the section's label instead of the page.
• Pointer placement: the usage pointer sits at the end of "Parse a name". The rewrite may give it a better place, as long as the anchor stays on usage.html.

🤖 Generated with Claude Code