Repository navigation
docs: migrate the documentation to Read the Docs - #136
Conversation
The declarations typed it as { profile?: string }, but the implementation
takes { ciphers, sigalgs, ecdhCurve }, so a TypeScript caller could not
pass a working override.
Replace MkDocs on GitHub Pages with Sphinx (MyST) and the Read the Docs theme. The per-language pages become one page per topic, with the examples of the three SDKs in synced tabs, plus reference pages for the client methods, Flight, Airport and the countries. Read the Docs publishes the site; the new Docs workflow only checks that the build has no warnings.
The docs belong to the whole repository, so their targets (install-docs, docs, docs-serve, docs-clean) move to a Makefile at the root. The docs targets of python/Makefile forward to it.
There was a problem hiding this comment.
🟡 Changes recommended
The documentation contains unsafe examples for partial or missing flight data and inaccurate descriptions of coordinate failures, Python retries, and Node.js response-size limits.
5 open issues
Represent missing flight coordinates as null, not "N/A" · New Document retries of permanent Python HTTP errors · New Clarify Node.js response limit applies after decompression · New Handle partial flight results when detail requests fail · New Skip flights with missing altitude before filtering · New
What changed in this PR
Migrates the three SDKs’ documentation from MkDocs on GitHub Pages to Sphinx/MyST on Read the Docs, with shared topic pages and synchronized language tabs.
Changes:
- Adds cross-language guides and API references, replacing language-specific pages.
- Introduces Sphinx build tooling and documentation checks, and updates public documentation links.
- Corrects Node.js TLS impersonation types and adds declaration tests.
| File | Description |
|---|---|
README.md |
Adds documentation badge and updates site link. |
python/README.md |
Updates documentation link and Go version badge. |
python/pyproject.toml |
Points package metadata to Read the Docs. |
python/Makefile |
Replaces MkDocs commands with Sphinx tooling. |
nodejs/tests/index.test-d.ts |
Tests TLS impersonation option types. |
nodejs/README.md |
Updates documentation link. |
nodejs/FlightRadarAPI/index.d.ts |
Aligns impersonation options with runtime fields. |
mkdocs.yml |
Removes obsolete MkDocs configuration. |
go/README.md |
Updates documentation link. |
docs/zones.md |
Adds zones and geographic bounds guide. |
docs/tracker-config.md |
Documents flight tracker settings. |
docs/searching.md |
Adds search usage and result reference. |
docs/sdk-differences.md |
Compares the three SDK interfaces. |
docs/requirements.txt |
Pins Sphinx documentation dependencies. |
docs/quickstart.md |
Adds cross-language getting-started examples. |
docs/python.md |
Removes superseded Python-only guide. |
docs/projects.md |
Converts project showcase to MyST cards. |
docs/nodejs.md |
Removes superseded Node.js-only guide. |
docs/live-data.md |
Documents tracking, disruptions and eruptions. |
docs/license.md |
Includes the repository license. |
docs/installation.md |
Documents installation and runtime requirements. |
docs/index.md |
Rebuilds the landing page and navigation. |
docs/go.md |
Removes superseded Go-only guide. |
docs/flights.md |
Adds flight search and details guide. |
docs/flight.md |
Adds flight attributes and methods reference. |
docs/errors.md |
Documents failures, retries and response limits. |
docs/distances.md |
Explains distance calculations between entities. |
docs/countries.md |
Lists country constants and slugs. |
docs/contributing.md |
Includes repository contribution guidance. |
docs/conf.py |
Configures Sphinx, MyST and theme extensions. |
docs/client.md |
Documents client configuration and logging. |
docs/api.md |
Adds client signatures and package exports. |
docs/airports.md |
Adds airport lookup and listing guide. |
docs/airport.md |
Adds airport attributes and methods reference. |
docs/airlines.md |
Documents airlines, logos and flags. |
docs/account.md |
Documents login, bookmarks and flight history. |
docs/_templates/layout.html |
Adds sidebar repository link and statistics. |
docs/_static/custom.css |
Styles navigation, tabs and reference tables. |
CONTRIBUTING.md |
Adds documentation build and update guidance. |
.readthedocs.yaml |
Configures hosted documentation builds. |
.gitignore |
Ignores Sphinx output instead of MkDocs output. |
.github/workflows/labeler.yml |
Recognizes Read the Docs configuration changes. |
.github/workflows/docs.yml |
Adds warning-failing Sphinx build checks. |
.github/workflows/deploy-docs.yml |
Removes GitHub Pages deployment workflow. |
.github/docs-requirements.txt |
Removes obsolete MkDocs dependencies. |
Review effort: Balanced
The home page opens with the description and the educational-use notice, followed by a Getting Started example; its Go tab is now a complete program. The zones table, the dependency column and the SDK differences page are removed.
Tables that carried a column per language now show one language per tab, in sync with the rest of the site. The full list of countries, the method signatures, the list of exported names and the sections on building a Flight or an Airport by hand are removed, and the three live-data sections become one.
There was a problem hiding this comment.
🟡 Changes recommended
Documentation still contains examples that fail on request errors, missing data, or Node.js syntax, plus inaccurate claims about coordinate handling, retries, and download limits.
7 open issues
Document missing-coordinate behavior and validate coordinates before distance c… · New Wrap the CommonJS example's top-level await in an async function · New Skip flights with missing altitude before filtering Handle partial flight results when detail requests fail Clarify Node.js response limit applies after decompression Document retries of permanent Python HTTP errors Represent missing flight coordinates as null, not "N/A"
Review effort: Balanced
The site is published as a single version.
Wrap the Node.js home example in an async function, check the error in the Go details example, and describe what really happens with a missing flight value: check_info comparisons, distances, what each SDK retries and where the response size limit applies.
There was a problem hiding this comment.
🔵 Needs a closer look
Human assessment is needed to evaluate an unpublished finding that logout leaves anonymous-request cookies intact when no session is active.
No open issues 🎉
7 resolved since last review
Wrap the CommonJS example's top-level await in an async function Document missing-coordinate behavior and validate coordinates before distance c… Skip flights with missing altitude before filtering Handle partial flight results when detail requests fail Clarify Node.js response limit applies after decompression Document retries of permanent Python HTTP errors Represent missing flight coordinates as null, not "N/A"
Review effort: Balanced
Replace the emoji-style airplane with an original vector logo, with the PNG and the favicon rendered from it, and add the Read the Docs badge to the docs home page and to the README of each package.
Show the yearly and monthly npm downloads on the docs home page, the root README and the Node.js README, which now carries the npm download badges only. The PyPI total is labelled as such.

Why is this PR necessary, what does it do?
Moves the documentation from MkDocs on GitHub Pages to Sphinx (MyST) with the Read the Docs theme, and rewrites it from the source of the three SDKs.
FlightandAirport, and how countries are named. The Go-specific comparison table ofdocs/go.mdis dropped; the per-language tabs cover the differences.get_history_datadocumented as taking a flight ID when it takes aFlight, a Python example with broken indentation, andawaiton the synchronousgetZones()..readthedocs.yaml, pinneddocs/requirements.txt, aDocsworkflow that fails on any Sphinx warning, and a rootMakefilewithmake install-docs/make docs/make docs-serve.mkdocs.yml,.github/docs-requirements.txtand the Pages deploy workflow are removed.impersonatewas declared as{ profile?: string }while the client reads{ ciphers, sigalgs, ecdhCurve }, so a TypeScript caller could not pass a working override.Checklist (complete all items):
References:
No references to be shared.
Notes:
flightradarapi(https://flightradarapi.readthedocs.io/).-n -W; the attribute and country tables were cross-checked by script against the Python, Node.js and Go sources; the snippets that need no network were run against the three packages. Calls that reach FlightRadar24 were not executed.ImpersonateOptionsto what the implementation already required;tsdcovers it.🤖 Generated with Claude Code