72 lines
2.3 KiB
Markdown
72 lines
2.3 KiB
Markdown
# EdgeTX Developer Documentation
|
|
|
|
This folder contains the source for the EdgeTX developer documentation site, built with [MkDocs](https://www.mkdocs.org/) using the [Material theme](https://squidfunk.github.io/mkdocs-material/).
|
|
|
|
## Prerequisites
|
|
|
|
Install the required packages from the repo root. Using [`uv`](https://docs.astral.sh/uv/getting-started/installation/) is recommended:
|
|
|
|
```bash
|
|
uv pip install -r docs-requirements.txt
|
|
```
|
|
|
|
Or with plain pip:
|
|
|
|
```bash
|
|
pip install -r docs-requirements.txt
|
|
```
|
|
|
|
[`mike`](https://github.com/jimporter/mike) is included as a dependency — it manages versioned deployments of the site (e.g. publishing a new release). You won't need it for local editing or preview.
|
|
|
|
## Local preview
|
|
|
|
Serve the docs locally with live reload:
|
|
|
|
```bash
|
|
mkdocs serve
|
|
```
|
|
|
|
Then open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser. The site will automatically refresh as you edit files.
|
|
|
|
## Building
|
|
|
|
To build a static copy of the site into the `site/` directory:
|
|
|
|
```bash
|
|
mkdocs build
|
|
```
|
|
|
|
CI runs `mkdocs build --strict` on pull requests, which treats warnings (e.g. broken internal links) as errors. It's worth running this locally before submitting a PR to catch any issues early:
|
|
|
|
```bash
|
|
mkdocs build --strict
|
|
```
|
|
|
|
## Deployment
|
|
|
|
The docs are deployed automatically via GitHub Actions (`.github/workflows/docs.yml`):
|
|
|
|
- Pushes to `main` are deployed as the `latest` version.
|
|
- Release tags (e.g. `v2.11.0`) are deployed as a numbered version (e.g. `v2.11`) and aliased as `stable`.
|
|
|
|
## Project structure
|
|
|
|
```
|
|
docs/
|
|
├── assets/ # Images, stylesheets
|
|
├── building/ # Build guides (Windows, Linux, macOS, CodeSpaces)
|
|
├── contributing/ # Git workflow and contribution guides
|
|
├── development/ # Developer reference (CLI, protocols, etc.)
|
|
├── hardware/ # Radio specs and hardware reference
|
|
├── mods/ # Hardware modification guides
|
|
└── troubleshooting/ # Troubleshooting guides
|
|
```
|
|
|
|
Site navigation is defined in [`mkdocs.yml`](../mkdocs.yml) at the repo root.
|
|
|
|
## Adding or editing pages
|
|
|
|
1. Create or edit a `.md` file in the appropriate subfolder.
|
|
2. If adding a new page, add it to the `nav:` section in `mkdocs.yml`.
|
|
3. Preview with `mkdocs serve` and verify with `mkdocs build --strict` before submitting a PR.
|