feat: supplement JSON docs with XML documentation from Godot source#1
Merged
feat: supplement JSON docs with XML documentation from Godot source#1
Conversation
- Fix std.compress.gzip -> std.compress.flate reference - Add fallback for when Godot is not installed - Use tag-based tarball URL with hash fallback - Add error handling section with graceful degradation - Include modules/*/doc_classes/*.xml in tar filter - Add .complete marker for staleness/partial download detection - Specify Tutorial struct type and $DOCS_URL expansion - Clarify merge happens during cache generation, not display time - Note --godot-extension-api bypasses XML supplementation
10-task plan covering: zig-xml dependency, version parsing, tarball download/extraction, XML parsing, Entry tutorials field, cache integration, XML merge into DocDatabase, and e2e verification.
Add GDOC_NO_XML environment variable to disable XML doc supplementation. Set automatically in build.zig for test runs to avoid network I/O during zig build test.
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
zig-xmlto extract tutorials, descriptions, methods, properties, signals, and constantsGDOC_NO_XMLenv var to disable XML supplementation (set automatically duringzig build test)How it works
godot --versionto get the version/commit hashrefs/tags/{version}-stable.tar.gz, with commit hash fallback)*/doc/classes/*.xmland*/modules/*/doc_classes/*.xml~/.cache/gdoc/xml_docs/with a.completeversion marker$DOCS_URLin tutorial links is expanded tohttps://docs.godotengine.org/en/stableGodot must be installed. If
godot --versionfails or the download fails, XML supplementation is silently skipped and gdoc works with JSON-only data.--clear-cacheclears everything including XML docs.New files
src/source_fetch.zig— Version parsing, tarball URL building, HTTP download, streaming tar extraction, cache markerssrc/XmlDocParser.zig— Godot XML doc parser using zig-xml pull parserTest plan
zig build testpasses (~0.6s, no network I/O)gdoc --clear-cache && gdoc Node2Dshows tutorials section from XML docsgdoc Node2D.positionshows property documentationGDOC_NO_XML=1 gdoc --clear-cache && gdoc Node2Dworks without tutorials (JSON-only)