Skip to content

docs: migrate the documentation to Read the Docs - #136

Merged
JeanExtreme002 merged 11 commits into
mainfrom
docs/migrate-to-read-the-docs
Nov 15, 2026
Merged

JeanExtreme002 merged 11 commits into
mainfrom
docs/migrate-to-read-the-docs

Conversation

@JeanExtreme002

@JeanExtreme002 JeanExtreme002 commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

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.

  • One page per topic instead of one page per language. Every example is shown in Python, Node.js and Go, in tabs that stay in sync across the site.
  • New guides: searching, most tracked / disruptions / eruptions, logos and flags, login and bookmarks, client configuration (timeout, concurrency, TLS impersonation, logging), errors and retries.
  • New reference pages: client methods, the attributes of Flight and Airport, and how countries are named. The Go-specific comparison table of docs/go.md is dropped; the per-language tabs cover the differences.
  • Fixes to the old pages: "area line" for "airline", get_history_data documented as taking a flight ID when it takes a Flight, a Python example with broken indentation, and await on the synchronous getZones().
  • Tooling: .readthedocs.yaml, pinned docs/requirements.txt, a Docs workflow that fails on any Sphinx warning, and a root Makefile with make install-docs / make docs / make docs-serve. mkdocs.yml, .github/docs-requirements.txt and the Pages deploy workflow are removed.
  • Node.js typing fix (separate commit): impersonate was 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):

  • Added tests as necessary.
  • There is no breaking change for existing features.

References:

No references to be shared.

Notes:

  • The Read the Docs project still has to be imported on readthedocs.org. The links and the badge assume the slug flightradarapi (https://flightradarapi.readthedocs.io/).
  • GitHub Pages should be turned off after the merge: nothing deploys to it anymore, so it would keep serving the old site. The READMEs already published on PyPI and npm (1.7.0) link to it.
  • How it was checked: the Sphinx build passes with -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.
  • The typing change only narrows ImpersonateOptions to what the implementation already required; tsd covers it.

🤖 Generated with Claude Code

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.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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
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

Comment thread docs/distances.md Resolved
Comment thread docs/errors.md Resolved
Comment thread docs/errors.md Resolved
Comment thread docs/flights.md Resolved
Comment thread docs/flights.md Resolved
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.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread docs/distances.md Resolved
Comment thread docs/index.md Resolved
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.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
@JeanExtreme002
JeanExtreme002 merged commit bbc07ed into main Nov 15, 2026
12 checks passed
@github-actions
github-actions Bot deleted the docs/migrate-to-read-the-docs branch November 15, 2026 03:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants