gdscript_to_docs

Export Godot 4.x GDScript documentation comments (## blocks) into clean Markdown, Doxygen-style class pages, and optional per-function pages — with BBCode → Markdown conversion and cross-links to referenced classes/methods/signals.

• Parses ## doc comments above members (Godot style)
• Detects func, var, const, signal, enum
• Converts BBCode: [b], [i], [u], [code], [codeblock], [url], [img], [br], …
• Cross-reference tags (linking in “References”):
  [method …], [member …], [signal …], [constant …], [enum …], [class …], plus Godot-style extras:
  [Class …], [annotation …], [constructor …], [operator …], [theme_item …]
• Parameters/Return parsing in function docs:
  Start-of-line [param name] desc… → bullet list; [return] desc… → “Return Value” bullet; inline [param name] → `name`
• Per-function pages (--split-functions) with full source, file/line range, and a References section
• Structured index: small INDEX.md dashboard + _index/by-folder.md, _index/classes.md, and (if split) _index/functions.md
• Handles decorators robustly (e.g. @export_file("*.tres"), @export_range(...)) and attaches docblocks to exported vars correctly

Compatible with Windows, macOS, and Linux. Tested on Python 3.12–3.13.

---

Install

# From PyPI
pip install gdscript-to-docs

# Latest from source (editable)
pip install -e .

Quick Start

From your Godot project root (or any folder containing .gd files):

gdscript_to_docs path/to/project \
  --out docs/ \
  --make-index \
  --split-functions

Windows example (be sure to quote paths with spaces / backslashes):

gdscript_to_docs "\path\to\godot\project" --out ".\docs" --keep-structure --make-index --split-functions

This generates:

docs/
├─ INDEX.md                     # tiny dashboard
├─ _index/
│  ├─ by-folder.md              # classes grouped by folder
│  ├─ classes.md                # A–Z class list
│  └─ functions.md              # A–Z global function list (only if split-functions)
├─ Player.md                    # class page
└─ Player/
   └─ functions/
      └─ move.md                # per-function page (if split)

CLI

usage: gdscript_to_docs [-h] [--out OUT] [--keep-structure] [--single-file]
                        [--make-index] [--glob GLOB]
                        [--style {doxygen,classic}] [--split-functions]
                        src

Export Godot GDScript documentation comments to Markdown.

positional arguments:
  src                   Project root (or any folder) to scan for .gd files

options:
  -h, --help            show this help message and exit
  --out OUT             Output directory (default: docs_godot)
  --keep-structure      Mirror source folder structure under output
  --single-file         Write a single DOCUMENTATION.md instead of per-script files
  --make-index          Generate an INDEX.md linking all generated files
  --glob GLOB           Glob pattern for .gd scripts (default: **/*.gd)
  --style {doxygen,classic}
                        Markdown style (default: doxygen)
  --split-functions     Also generate separate Markdown files for each function

Output style

Doxygen-style class pages (default)

• ClassName Class Reference

• Synopsis with class_name and extends
• Brief and Detailed Description
• Public Member Functions/Attributes/Constants/Signals/Enumerations summaries
• Detailed sections (e.g. Member Function Documentation)

Per-function pages (--split-functions)

• Title: ClassName::method Function Reference
• Defined at: <file> with line range
• Signature (code block)
• Decorators (e.g. @export)
• Description (from the ## docblock)
• Source: full function body (code block)
• References: links generated from doc tags like:
  • [method Class.foo] → either the per-function page (if split) or class page + anchor
  • [class Foo] → class page
  • [signal Class.sig], [member Class.var], [constant Class.NAME], [enum Class.Enum] → class page + anchor

If a target isn’t found in the generated docs, it’s rendered as plain text to avoid broken links.

BBCode → Markdown

References

Supported in docs and turned into links in the references section.

[class Foo], [Class Foo]     # link to class page
[method Foo.bar]             # link to per-function page (if split) or class+anchor
[member Foo.prop], [signal Foo.sig], [constant Foo.NAME], [enum Foo.Enum]
[annotation @GDScript.@rpc], [constructor Color.Color], [operator Color.operator *], [theme_item Label.font]

Parameters / Return

Place at the start of a line to become list bullets:

## Describes movement. [method CharacterBody2D.move_and_slide]
## [param speed] units per second
## [param accel] acceleration
## [return] true if ok
func move(speed: float, accel: float) -> bool:
    pass

Renders as:

• Summary bullet: func move(delta: float) -> void — Describes movement.
• Function page includes the doc text and a References link to CharacterBody2D::move_and_slide.
• speed: units per second
• accel: acceleration
• Return Value: true if ok Inline [param speed] in prose renders as speed.

Example:

## Moves the player.
## [b]Use with care[/b]. [method CharacterBody2D.move_and_slide]
func move(delta: float) -> void:
    pass

Index & single-file bundle

• --make-index writes an INDEX.md that lists class pages and, if split, function pages beneath each class.
• --single-file writes a DOCUMENTATION.md that concatenates all class pages (helpful for quick review or importing into docs tools).

Known limitations / roadmap

• Multi-line function signatures aren’t yet parsed; signatures are expected on a single line.
• Links to external Godot classes (i.e., not in your project) are rendered as plain labels; you can map those to the online docs in a future --godot-api-links option.
• Anchors for members use a conservative GitHub-style ID; if you post-process headers, anchors may change.

Want any of the above? Please open an issue or a PR—contributions welcome!

Development

# Clone and install in editable mode
git clone https://github.com/<YOUR_GH_USER>/<YOUR_REPO>.git
cd <YOUR_REPO>
pip install -e .[dev]

# Run tests
pytest -q --cov --cov-report=term-missing:skip-covered

# Build
python -m pip install build
python -m build  # dist/*.whl and dist/*.tar.gz

License

MIT © Phase Line Studios