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] --path PATH [PATH ...] [--filter FILTER [FILTER ...]] --output OUTPUT

    Convert godot documentation xml file to yml for docfx.

    options:
      -h, --help            show this help message and exit
      --path PATH [PATH ...]
                            A path to an XML file or a directory containing XML files to parse.
      --filter FILTER [FILTER ...]
                            Regex filepath patterns for XML files to filter.
      --output OUTPUT       Output folder to store all generated yml files.

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

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

    options:
      -h, --help            show this help message and exit
      --path PATH [PATH ...]
                            A path to an XML file or a directory containing XML files to parse.
      --filter FILTER [FILTER ...]
                            Regex filepath patterns for XML files to filter.
      --output OUTPUT       output path to store xrefmap.

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 --path doc/my-classes ref --output 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 --path godot/doc/classes godot/modules --output 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.

# Download submodules
git submodule update --init godot

# Install from repo
python3 -m pip install .

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

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

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