Repository navigation
docs: use fictitious data and make the phone reference reachable - #67
Merged
Merged
Conversation
lhagenWP
force-pushed
the
phone-docs-followup
branch
from
October 2, 2026 17:54
290af0e to
1c86ef2
Compare
The phone lookup examples were a live response captured from a running service: a real business, its real carrier, its real number. Replace them with fictitious values on the pattern the other guides already use, from the 555-01xx range reserved for documentation, and say so in the guide. The business example stays, since approximate_locations needs one to illustrate, but the business is invented too. The reference page had no way in. The References rail lists its directories by hand and phone-v2 was missing from that list, so the page was reachable only by typing its URL. Getting Started mentioned a phone number only as something person search accepts.
The service stopped publishing its handler docstrings, so the spec these pages are generated from no longer carries numpydoc sections or the reStructuredText markup the site renders as literal backticks. Descriptions only. Five pages: the phone lookup loses a Parameters and Returns block naming Python arguments and internal types, person, property and deed-event search lose Raises blocks naming exception classes, and the property detail page's code spans render as code.
lhagenWP
force-pushed
the
phone-docs-followup
branch
from
October 2, 2026 19:43
1c86ef2 to
b5ace22
Compare
trichardswp
approved these changes
Oct 2, 2026
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.
Why
Two things that shipped in the phone lookup docs need correcting.
The examples were real. They were a response captured from a running
service: an identifiable business, its carrier, its number. They are published
now.
The reference page has no way in.
/references/phone-v2/get_phone_by_number_v2exists and renders, but the References rail lists its directories by hand and
phone-v2was not among them. A reader reaches the page only by typing theURL. Getting Started mentions a phone number only as something person search
accepts as a parameter.
What Changed
Examples in the guide and the changelog are fictitious:
John Smithon(206) 555-0142, placeholder identifiers, matching what the other guides use.Phone numbers come from the
555-01xxrange reserved for documentation, and acallout on the guide says the values are invented so nobody mistakes them for
live data.
The business example stays, because
approximate_locationsneeds a business toillustrate and that is the endpoint's new capability — but the business is
invented too.
phone-v2is added to the References rail, afterperson-v2. Getting Startedgains a Phone Lookup card beside Person Search and a mention in Next Steps.
The reference pages are regenerated from the published spec, as a second
commit. The service stopped publishing its handler docstrings, so the spec no
longer carries numpydoc sections or the reStructuredText markup this site
renders as literal backticks. Descriptions only, on five pages: the phone
lookup loses a
ParametersandReturnsblock naming Python arguments andinternal types; person, property and deed-event search lose
Raisesblocksnaming exception classes; the property detail page's code spans render as code.
Context
The rail file is hand-maintained; the generator writes each directory's own
meta.jsonbut not the parent list, which is why generating the page did notmake it reachable. Worth knowing for the next endpoint that gets added.
The regeneration had to wait for the service change to reach production, since
the generator reads the live spec at
api.whitepages.com/openapi.json. Iconfirmed the deployed image is that change's merge commit and that the live
spec has no remaining leaked sections before regenerating.