1 unstable release

0.1.0 Jun 25, 2020

#1108 in Rust patterns

GPL-3.0-only

62KB
1.5K SLoC

GodotDoc

GodotDoc is a documentation generator for GdScript.

It extracts all symbols and the surrounding comments and generates a markdown file for display in, e.g. github.

Consider the following example:

# This comment is a description of the method foo
func foo(id):
	return id + 42

# We can exclude functions from showing up
# [Hide]
func _bar():
	return 1337

# Besides functions, one can declare classes, enums, variables, constants
class MyClass:
	# One can even comment on individual variables in a class or enum
	var baz
	var test # Even comments on the same line as the declaration are honored

# Enums list all values
enum MyEnum {
	FIRST = 0, # This is the first entry
	SECOND,
	GAP = 42, # Here we have a gap in the numbering
	LAST
}

# Export arguments are honored too
export(int, 1, 8) var my_export = 5

# As well as types
const MY_CONST: int = 42

# Setter and getter will be visible in the docs as well
var my_var setget foo, _bar

You can now invoke godotdoc /path/to/source/directory -o /path/to/output/directory

This will be the result:

test.gd

Classes:

  • MyClass

    Besides functions, one can declare classes, enums, variables, constants
    
    • Variables:

      • baz
      One can even comment on individual variables in a class or enum
      
      • test
      Even comments on the same line as the declaration are honored
      

Enums:

  • MyEnum
    Values:

    • FIRST = 0
    This is the first entry
    
    • SECOND = 1
    • GAP = 42
    Here we have a gap in the numbering
    
    • LAST = 43

Exports:

  • my_export: (int, 1, 8) = 5

    Export arguments are honored too
    

Constants:

  • MY_CONST: int = 42

    As well as types
    

Functions:

  • foo(id)

    This comment is a description of the method foo
    

Variables:

  • my_var
    Getter: _bar
    Setter: foo

    Setter and getter will be visible in the docs as well
    

GodotDoc will try to read a file named godotdoc_config.json from the source directory. This file can provide a project wide configuration of the generated files. This could be an example configuration:

{
    "backend": "markdown",
    "excluded_files": [
        "./path/to/secret/directory",
	"./or/some/pattern/*.gd"
    ],
    "show_prefixed": true
}

This will set the default backend for document generation to markdown (the only available backend for now) and exclude "path/to/secret/directory" and all .gd files in "or/some/pattern" from being processed. The option "show_prefixed" controls, wether members prefixed by a "_" will show up. This can be overridden on a per member basis, via # [Show] and # [Hide]

These default values can be overriden by command line arguments, e.g. --backend=markdown to set the backend to use (excluded_files can not be set via arguments).

Installation instructions

This application is written in rust, therefore you need to install the Rust toolchain

To install this application:

  1. Clone this repository: git clone https://github.com/Dragoncraft89/godotdoc.git
  2. Invoke cargo, the rust package manager to install it "cargo install --path godotdoc"

Dependencies

~1.4–2.5MB
~41K SLoC