Godot Doc 2 Yml

Convert godot xml docs exported via the godot --doctool for gdscript to yml compatible with docfx.

Install

Install gddoc2yml via pip

python3 -m pip install gddoc2yml

Then you will have the gdxml2yml and gdxml2xrefmap command available:

gdxml2yml -h
    usage: gdxml2yml [-h] [--filter FILTER] path [path ...] output

    Convert godot documentation xml file to yml for docfx.

    positional arguments:
    path             A path to an XML file or a directory containing XML files to parse.
    output           output folder to store all generated yml files.

    options:
    -h, --help       show this help message and exit
    --filter FILTER  The filepath pattern for XML files to filter

gdxml2xrefmap -h
    usage: gdxml2xrefmap [-h] [--filter FILTER] path [path ...] output

    Convert godot documentation xml files into a xrefmap compatible with DoxFx.

    positional arguments:
    path             A path to an XML file or a directory containing XML files to parse.
    output           output path to store xrefmap.

    options:
    -h, --help       show this help message and exit
    --filter FILTER  The filepath pattern for XML files to filter.

Using gddoc2yml

Export xml docs for your project with godot, us gdxml2yml to generate yml api, then use the gd

1. Generate xml docs for your project.

   Install godot command line tool (see Godot's Command Line Tutorial for details).

   Export docs for your gdscript to xml via the --doctool flag.

   # Example command to generate docs from scripts in project/scripts to dir doc/my-classes
   godot --path project --doctool doc/my-classes --gdscript-docs res://scripts

2. Use gdxml2yml to generate yml docs for your project. See references section for details on yml schema.

   # You will also need the original xml docs from
   # the godot repo, generate via godot --doctool <path>
   # to generate godot docs at a given path
   #   $ mkdir ref
   #   $ godot --doctool ref
   
   # Generate yml api for docfx.
   # Generates output at folder out/my-classes/api
   # Use the '--filter' flag to only generate docs for your files
   gdxml2yml --filter doc/my-classes doc/my-classes ref out/my-classes/api

3. Use your generated yml in docfx. see the doc/docfx.json for an example. Make sure to include your api folder in the doc content

   {
       "files": ["*.yml"],
       "src": "api",
       "dest": "api"
   },

Generating xrefmap for Godot Docs

Included is an additional command, gdxml2xrefmap to generate an xrefmap for the godot docs.

gdxml2xrefmap godot/doc/classes godot/modules out/godot_xrefmap.yml

Note the build for this repo contains an xrefmap that points to godot's documentation. You can reference this in your docfx.json file as a xref like so:

{
  "build": {
    "xref": [
      "https://gddoc2yml.nickmaltbie.com/xrefmap/godot_xrefmap.yml"
    ]
  }
}

References

• Godot -- CLI Reference
• Godot -- make_rst.py
• DocFx -- Github
• DocFx -- Introduction to Multiple Languages Support
• DocFx -- Custom Template
• DocFx -- .NET API Docs YAML Format
• DocFx -- PageViewModel.cs
• DocFx -- ItemViewModel.cs
• DocFx -- Recommended XML tags for C#

Development

This section consists of how to build and test the gddoc2yml project.

Setup

Build package

# Install dependencies
python3 -m pip install -r requirements.txt

# Install build if required
# python3 -m pip install build
# Project will be created in dir dist
python3 -m build

Linting

Lint using flake8 tool.

# Run flake8 from .flake8 config file
# Install via python3 -m pip install flake8
python3 -m flake8 .

Markdown Linting

Markdown linting via markdownlint can be installed via npm.

# Install cli version via npm
npm install -g markdownlint-cli

# Run on local repo
markdownlint .

Tests

Run tests for project via Python's unittest module -- Unit testing framework

python3 -m unittest

Code Coverage

Compute code coverage using coveragepy

# Get code coverage using coverage
# Install via python -m pip install coverage
coverage run -m unittest discover

# Get results
coverage report -m

Build and Use Latest Version

Build godot docs using latest gddoc2yml.

# Install from repo
python3 -m pip install .

# Generate docs using gdxml2yml
gdxml2yml godot/doc/classes godot/modules godot/platform/android/doc_classes doc/godot/api

# Generate xrefmap using gdxml2xrefmap
gdxml2xrefmap godot/doc/classes godot/modules doc/xrefmap/godot_xrefmap.yml

# Startup docfx website
dotnet tool run docfx --serve doc/docfx.json