docs: migrate the documentation to Read the Docs

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs
+
+# The documentation builds without warnings. Read the Docs publishes it; this
+# only checks that a change does not break the build.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.readthedocs.yaml'
+      - 'CONTRIBUTING.md'
+      - 'LICENSE'
+      - 'python/FlightRadarAPI/__init__.py'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.readthedocs.yaml'
+      - 'CONTRIBUTING.md'
+      - 'LICENSE'
+      - 'python/FlightRadarAPI/__init__.py'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Warnings (including broken cross-references, via -n) fail the build, the
+  # same as on Read the Docs.
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: '3.11'
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Build docs
+        run: python -m sphinx -n -W --keep-going -b html docs docs/_build/html

.github/workflows/labeler.yml

@@ -84,7 +84,7 @@ jobs:
 
             const isDocs = (f) =>
               f.startsWith("docs/") ||
-              f === "mkdocs.yml" ||
+              f === ".readthedocs.yaml" ||
               /\.md$/i.test(f);
 
             const isPython = (f) => f.startsWith("python/");

.gitignore

@@ -13,7 +13,6 @@ venv/
 .mypy_cache/
 .pytest_cache/
 htmlcov/
-site/
 .coverage
 coverage.xml
 
@@ -34,6 +33,9 @@ coverage.out
 .DS_Store
 Thumbs.db
 
+# Docs build output
+docs/_build/
+
 # Misc
 .env
 .cache

.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration file for Sphinx + MyST.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -9,30 +9,30 @@ touch every side.
 ### Python
 ```bash
 cd python
-make dev-setup          # creates venv, installs package + test extras + tooling
+make dev-setup            # creates venv, installs package + test extras + tooling
 source venv/bin/activate
-make test               # runs offline + integration
-make lint               # flake8
-make type-check         # mypy
+make test                 # runs offline + integration
+make lint                 # flake8
+make type-check           # mypy
 ```
 
 ### Node.js
 ```bash
 cd nodejs
 make install
-make test               # mocha (all tiers)
-make lint               # eslint
-make test-types         # tsd
+make test                 # mocha (all tiers)
+make lint                 # eslint
+make test-types           # tsd
 ```
 
 ### Go
 ```bash
 cd go
 make deps
-make test               # offline suite (the PR gate)
-make test-integration   # live FR24 suite
-make lint               # gofmt + go vet
-make lint-strict        # adds staticcheck
+make test                 # offline suite (the PR gate)
+make test-integration     # live FR24 suite
+make lint                 # gofmt + go vet
+make lint-strict          # adds staticcheck
 ```
 
 ## Keeping the SDKs aligned
@@ -47,7 +47,25 @@ is a documented reason not to. Common targets that must stay in sync:
 - The public surface — `FlightRadar24API` methods (`Client` in Go), the
   `Countries` enum (`Country` constants in Go), `FlightTrackerConfig` fields,
   and the `Entity` / `Airport` / `Flight` attributes consumers depend on.
-  `docs/go.md` documents where the Go surface deliberately differs.
+
+## Documentation
+
+The documentation lives in `docs/`, written in Markdown (MyST) and built with
+Sphinx. It is published on [Read the Docs](https://flightradarapi.readthedocs.io/)
+from `main`, and every pull request gets a preview build.
+
+```bash
+make venv               # optional: creates .venv, which the targets below then use
+make install-docs       # installs Sphinx and the theme
+make docs               # builds into docs/_build/html
+make docs-serve         # live-reload server at http://127.0.0.1:8000
+```
+
+Run these from the repository root. Warnings fail the build, here and in CI.
+
+Each page shows its examples in the three languages, in tabs. When a change
+reaches the public surface, update the guide that covers it and the reference
+pages (`docs/api.md`, `docs/flight.md`, `docs/airport.md`, `docs/countries.md`).
 
 ## Style
 
@@ -100,5 +118,5 @@ module was tagged by hand, does what you would expect and nothing else.
 ## Reporting bugs and asking questions
 
 - Bugs: open a GitHub issue with the bug report template.
-- Security: see [`SECURITY.md`](SECURITY.md). **Do not** report via GitHub
-  issues.
+- Security: see [`SECURITY.md`](https://github.com/JeanExtreme002/FlightRadarAPI/blob/main/SECURITY.md).
+  **Do not** report via GitHub issues.

Makefile

@@ -0,0 +1,76 @@
+# Makefile for the FlightRadarAPI documentation.
+#
+# Each SDK has its own Makefile (python/, nodejs/, go/). This one covers what
+# belongs to the repository as a whole: the documentation.
+
+# Variables
+VENV_DIR = .venv
+DOCS_DIR = docs
+DOCS_BUILD_DIR = $(DOCS_DIR)/_build/html
+
+# Use the virtual environment when `make venv` has created it.
+ifneq ($(wildcard $(VENV_DIR)/bin/python),)
+PYTHON := $(VENV_DIR)/bin/python
+else
+PYTHON := python3
+endif
+PIP = $(PYTHON) -m pip
+
+# Colors for output
+GREEN = \033[0;32m
+YELLOW = \033[0;33m
+NC = \033[0m # No Color
+
+# Default target
+.PHONY: help
+help:
+	@echo "$(GREEN)FlightRadarAPI documentation Makefile$(NC)"
+	@echo ""
+	@echo "Setup:"
+	@echo "  $(YELLOW)venv$(NC)             - Create a virtual environment in $(VENV_DIR)"
+	@echo "  $(YELLOW)install-docs$(NC)     - Install the dependencies to build the documentation"
+	@echo ""
+	@echo "Documentation:"
+	@echo "  $(YELLOW)docs$(NC)             - Build the HTML documentation (output: $(DOCS_BUILD_DIR))"
+	@echo "  $(YELLOW)docs-serve$(NC)       - Live-reload docs server at http://127.0.0.1:8000"
+	@echo "  $(YELLOW)docs-clean$(NC)       - Remove the docs build directory"
+	@echo ""
+	@echo "The SDKs have their own Makefiles: python/, nodejs/ and go/."
+
+# Create virtual environment. `python3` literally: $(PYTHON) may already point
+# at the environment being created.
+.PHONY: venv
+venv:
+	@echo "$(GREEN)Creating virtual environment...$(NC)"
+	python3 -m venv $(VENV_DIR)
+	@echo "$(YELLOW)To activate: source $(VENV_DIR)/bin/activate$(NC)"
+
+# Install the documentation dependencies. The build imports nothing from the
+# SDKs, so none of them has to be installed.
+.PHONY: install-docs
+install-docs:
+	@echo "$(GREEN)Installing documentation dependencies...$(NC)"
+	$(PIP) install -r $(DOCS_DIR)/requirements.txt
+
+# Build the HTML documentation with the same flags as CI and Read the Docs:
+# warnings, including broken cross-references (-n), fail the build.
+.PHONY: docs
+docs:
+	@echo "$(GREEN)Building HTML documentation...$(NC)"
+	$(PYTHON) -m sphinx -n -W --keep-going -b html $(DOCS_DIR) $(DOCS_BUILD_DIR)
+	@echo "$(GREEN)Documentation generated at $(DOCS_BUILD_DIR)/index.html$(NC)"
+
+# Live-reload docs server. sphinx-autobuild is installed on demand. After
+# changing a toctree, restart it: it only rebuilds changed pages, so the
+# sidebar on the other pages goes stale.
+.PHONY: docs-serve
+docs-serve:
+	@echo "$(GREEN)Starting live-reload docs server at http://127.0.0.1:8000$(NC)"
+	@$(PYTHON) -c "import sphinx_autobuild" 2>/dev/null || $(PIP) install sphinx-autobuild
+	$(PYTHON) -m sphinx_autobuild $(DOCS_DIR) $(DOCS_BUILD_DIR) --open-browser
+
+# Wipe the built docs
+.PHONY: docs-clean
+docs-clean:
+	@echo "$(GREEN)Cleaning docs build directory...$(NC)"
+	rm -rf $(DOCS_DIR)/_build

README.md

@@ -5,6 +5,7 @@ This SDK should only be used for your own educational purposes. If you are inter
 
 **Official FR24 API**: https://fr24api.flightradar24.com/
 
+[![Documentation Status](https://readthedocs.org/projects/flightradarapi/badge/?version=latest)](https://flightradarapi.readthedocs.io/?badge=latest)
 [![Python Package](https://github.com/JeanExtreme002/FlightRadarAPI/workflows/Python%20Package/badge.svg)](https://github.com/JeanExtreme002/FlightRadarAPI/actions)
 [![Node.js Package](https://github.com/JeanExtreme002/FlightRadarAPI/actions/workflows/node-package.yml/badge.svg)](https://github.com/JeanExtreme002/FlightRadarAPI/actions)
 [![Go Package](https://github.com/JeanExtreme002/FlightRadarAPI/actions/workflows/go-package.yml/badge.svg)](https://github.com/JeanExtreme002/FlightRadarAPI/actions)
@@ -35,7 +36,7 @@ go get github.com/JeanExtreme002/FlightRadarAPI/go@latest
 ```
 
 ## Documentation
-Explore the docs of FlightRadarAPI package, for Python, NodeJS or Go, through [FlightRadarAPI Documentation](https://JeanExtreme002.github.io/FlightRadarAPI/) page.
+Explore the docs of FlightRadarAPI package, for Python, NodeJS or Go, through [FlightRadarAPI Documentation](https://flightradarapi.readthedocs.io/) page.
 
 ## Project resources
 **Contributing**: [`CONTRIBUTING.md`](CONTRIBUTING.md)<br>