Repository navigation
chore: make main a copy of edgetx_2.12 (MkDocs, published as dev) - #17
Merged
Merged
Conversation
) Replaces this repo's GitBook-based publishing with a versioned MkDocs Material site built by mike. The API reference (constants, functions, LVGL widgets) is now generated directly from /*luadoc*/ annotations in the EdgeTX firmware source (tools/docs_pipeline.py extracts a normalized model from those comment blocks and renders both the Markdown pages and a matching LuaLS .d.lua type-stub from it) instead of being hand-maintained separately, so a source annotation change is the only place a fact needs to change. Hand-authored guide content (Programming, API Overview, Radios) stays hand-authored -- this is a publishing-mechanism change, not a content rewrite; CONTRIBUTING.md documents which parts of the tree are generated vs. hand-edited. Also adds tools/import_legacy_gitbook.py, a one-time-per-version converter that brings each older GitBook-era branch's SUMMARY.md + content into the same MkDocs shell (with a banner marking it historical), and .github/workflows/publish-versioned-docs.yml, which deploys main -> dev and edgetx_2.12 -> latest via mike on push. This is squashed to a single commit on top of this branch's real history (rather than carrying the full history of the fork this was developed on, which had no common ancestor with this repo's own edgetx_2.12 and couldn't be opened as a normal PR) -- see the linked fork's commit history for the full incremental development record if useful during review. Claude-Session: https://claude.ai/code/session_01HLXbKn4rY3NihRnqH89jmD Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
mike still maintains the versioned site on the gh-pages branch; after each deploy the workflow exports that tree and uploads it to a Cloudflare Worker (assets only, no script) via wrangler-action. Also serialise publish runs so concurrent pushes to main and edgetx_2.12 can't race on gh-pages or upload a stale snapshot. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The importer mirrors every README.md to index.md, and MkDocs drops the README.md copy when both exist. Rewritten links still targeted README.md, so they 404'd -- including all four section links on the 2.11 homepage. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
main still held the GitBook-era tree and shared no history with edgetx_2.12. Merge with edgetx_2.12's tree as the result, so main becomes a copy of 2.12 (published as "dev") and later 2.12 fixes merge into main cleanly. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The legacy banner never rendered: it read extra.legacy_version from #__config, which Material doesn't populate. The banner script now works out the current version from the URL and mike's versions.json, showing a "Development version" notice on dev and a "Legacy version" notice (with a link to latest) on anything that isn't the latest alias. No per-version config is involved, so main can stay a straight copy of edgetx_2.12. Also turn on content.action.edit (Material hides the edit button without it) and take edit_uri from DOCS_EDIT_URI, which the publish workflow sets to the branch being built, so "Edit this page" on /dev/ opens main and on /2.12/ opens edgetx_2.12. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
edgetx_2.11 is still maintained but is GitBook content with no MkDocs config or tooling. The publish workflow can now be called via workflow_call; for GitBook-era branches it checks out the tooling from the latest release branch, converts the caller's branch with import_legacy_gitbook.py and deploys the generated config. edgetx_2.11 carries a small caller workflow, since a push there can only run workflows committed on that branch. Concurrency moves to job level so it also applies to called runs. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
All docs branches are MkDocs now, so the publish workflow no longer needs the GitBook import path or workflow_call: every branch carries the same file and builds itself. The latest release branch comes from the DOCS_LATEST_BRANCH repository variable (falling back to edgetx_2.12), so an older branch's copy can't take the "latest" alias back after a new release ships. Also adds preview-docs.yml, which uploads a Cloudflare preview for PRs into main or any edgetx_* branch. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
- actions/checkout v4 -> v7 - actions/setup-python v5 -> v7 - astral-sh/setup-uv v5 -> v10.3.2 (setup-uv no longer publishes major tags, so it's pinned to the release) Clears the Node.js 20 deprecation warnings. None of the breaking changes apply: no pull_request_target/workflow_run triggers, no pip-install or custom uv manifest. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
|
📖 Docs preview: https://pr-17-edgetx-lua-reference-guide.edgetx.workers.dev/dev/ Built from a63f0ae as the |
A single workflow-wide concurrency group dropped publishes: GitHub keeps only one pending run per group, so when the 2.4-2.11 conversions merged together, six of the eight runs were cancelled before they ran. Split the workflow into two jobs: - publish: one concurrency group per branch (a superseded pending run is harmless, since the newest push contains it). Branches build in parallel; if another branch updates gh-pages first, mike's push is rejected and the job rebuilds on the new tip and retries. - deploy: one group across all branches for the Cloudflare upload. It exports gh-pages when it starts, so whichever queued upload survives already includes every earlier publish. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
A relative filename gets the current language's sound directory put in front of it, so the language is prepended, not appended. The first example passes volume 5 but its comment said 2. Patched the playFile entry in the committed API model to match the upstream luadoc fix (EdgeTX/edgetx#7936) and regenerated with `docs_pipeline.py build`. The only outputs that change are the playFile page, its review page and the LuaLS stubs. Supersedes #10. Co-authored-by: Alex K <arkarkark@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.
Summary
mainstill held the old GitBook tree and shared no git history withedgetx_2.12, so the publish workflow had nothing it could build for thedevversion. This PR makesmainan exact copy ofedgetx_2.12: the MkDocs site, the pipeline tools, the Cloudflare deploy workflow andwrangler.jsonc.It's a single merge commit (
--allow-unrelated-histories) whose parents aremainandedgetx_2.12, and whose tree isedgetx_2.12's tree unchanged (git diff origin/edgetx_2.12 main-from-2.12is empty). Because the commit is a merge,edgetx_2.12becomes an ancestor ofmain, so future 2.12 fixes can be merged forward without conflicts.main's GitBook history is kept.Nothing from
mainis lost. Its last content change, the LUA_MIXER default-targets note in mixes-scripts, is already in 2.12'sapi-overview/script-types/mixes-scripts.md.uv run mkdocs build --strictpasses.Don't squash or rebase this PR. Either would flatten the merge, and
mainwould go back to sharing no history withedgetx_2.12.After merging
maintriggers the publish workflow, which deploysmainasdevon https://luadoc.edgetx.org/dev/ through mike and Cloudflare.devshows the same content as 2.12. Once firmwaremainhas API changes for the next release, regenerate the API reference onmainwithtools/docs_pipeline.py extract --docs-version dev --upstream-ref main(see CONTRIBUTING.md).🤖 Generated with Claude Code