{"id":14961658,"url":"https://github.com/gdquest/gdscript-docs-maker","last_synced_at":"2025-04-04T19:06:05.465Z","repository":{"id":39491646,"uuid":"236567996","full_name":"GDQuest/gdscript-docs-maker","owner":"GDQuest","description":"Create documentation and class references from your Godot GDScript code","archived":false,"fork":false,"pushed_at":"2024-05-16T10:26:04.000Z","size":205,"stargazers_count":273,"open_issues_count":12,"forks_count":26,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-04T19:05:48.431Z","etag":null,"topics":["documentation","documentation-tool","gdscript","godot","godot-engine","reference"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GDQuest.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-27T18:56:47.000Z","updated_at":"2025-03-29T10:32:19.000Z","dependencies_parsed_at":"2024-06-21T05:36:26.487Z","dependency_job_id":null,"html_url":"https://github.com/GDQuest/gdscript-docs-maker","commit_stats":{"total_commits":171,"total_committers":13,"mean_commits":"13.153846153846153","dds":"0.24561403508771928","last_synced_commit":"5c033fb3ff9f16fca5f0550fad68954e1e91740c"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GDQuest%2Fgdscript-docs-maker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GDQuest%2Fgdscript-docs-maker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GDQuest%2Fgdscript-docs-maker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GDQuest%2Fgdscript-docs-maker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GDQuest","download_url":"https://codeload.github.com/GDQuest/gdscript-docs-maker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234921,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-tool","gdscript","godot","godot-engine","reference"],"created_at":"2024-09-24T13:26:03.932Z","updated_at":"2025-04-04T19:06:05.416Z","avatar_url":"https://github.com/GDQuest.png","language":"Python","readme":"# GDScript Docs Maker\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/gdquest/gdscript-docs-maker)](https://github.com/GDQuest/gdscript-docs-maker) [![Docker Image Version (latest semver)](https://img.shields.io/docker/v/gdquest/gdscript-docs-maker?label=Docker%20tag\u0026sort=semver)](https://hub.docker.com/repository/docker/gdquest/gdscript-docs-maker)\n\n![Project banner](./assets/gdscript-docs-maker-banner.svg)\n\n# Introduction\n\nGDScript Docs Maker is a set of tools to convert documentation you write inside your code to an online or offline code reference in the [markdown](https://daringfireball.net/projects/markdown/syntax) or [hugo](https://gohugo.io/) format. If you make plugins or a framework for Godot, GDScript Docs Maker will generate API reference documentation from your code.\n\n**It is for Godot 3. The tool does not work with Godot 4.**\n\nGDScript Docs Maker creates documents following Godot's built-in class reference. You can see an example with our [Godot Steering Toolkit documentation](https://gdquest.gitbook.io/godot-3-steering-ai-framework-reference/)\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n\n- [Usage](#usage)\n    * [Using the container image](#using-the-container-image)\n    * [Local installation](#local-installation)\n    * [Writing your code reference](#writing-your-code-reference)\n    * [Generating the markdown files](#generating-the-markdown-files)\n    * [Hugo output](#hugo-output)\n- [The manual way](#the-manual-way)\n    + [Converting JSON](#converting-json)\n\n\u003c!-- markdown-toc end --\u003e\n\n# Usage\n\nGDScript Docs Maker can be either used using the official [Docker image](https://hub.docker.com/r/gdquest/gdscript-docs-maker) or by installing it locally. For the docker image, only [Docker](https://www.docker.com/get-started) is required.\n\nFor the local installation, Godot 3.2+ and Python 3.7+ are required. **Note that GDScript Docs Maker only works with Godot 3. It is not compatible with Godot 4.**\n\n## Using the container image\n\nTo generate your API documentation, you mount the path of your game and the path of the output into the container and run it like this:\n\n```\ndocker run --rm -v /my/game:/game -v /my/game/docs/api:/output gdquest/gdscript-docs-maker:latest /game -o /output\n```\n\nThis will generate the API documentation in the subpath `docs/api` of your game located at `/my/game`. See below for further parameters.\n\n## Local installation\n\nYou can install the GDScript Docs Maker python package with pip:\n\n```bash\n# On Linux and MacOS:\npython3 -m pip install gdscript_docs_maker\n\n# On Windows, if you installed Python 3.7+, you can use:\npython -m pip install gdscript_docs_maker\n```\n\nAlthough to use the shell script that simplifies creating the reference, `generate_reference`, you need to clone this repository. More on that below.\n\n## Writing your code reference\n\nDocstring or doc-comments in GDScript don't have any special markup.\n\nYou can document classes, properties, and functions with comment blocks placed on the line before their definition.\n\nExample of docstrings for Godot 3:\n\n```gdscript\n# A linear and angular amount of acceleration.\nclass_name GSTTargetAcceleration\n\n\n# Linear acceleration\nvar linear: = Vector3.ZERO\n# Angular acceleration\nvar angular: = 0.0\n\n\n# Resets the accelerations to zero\nfunc reset() -\u003e void:\n\tlinear = Vector3.ZERO\n\tangular = 0.0\n```\n\nIf you need long docstrings, you can use multiple commented lines:\n\n```gdscript\n## A specialized steering agent that updates itself every frame so the user does\n## not have to using a KinematicBody2D\n## category: Specialized agents\nextends GSAISpecializedAgent\nclass_name GSAIKinematicBody2DAgent\n```\n\n## Generating the markdown files\n\nWe wrote two shell scripts to automate the steps in generating a code reference: `./generate_reference` for Linux or MacOS, and `./generate_reference.bat` for Windows.\n\nUse either of them to quickly generate your code reference:\n\n```bash\nGenerate a code reference from GDScript\nUsage:\ngenerate_reference $project_directory [options]\n\nRequired arguments:\n\n$project_directory -- path to your Godot project directory.\nThis directory or one of its subdirectories should contain a\nproject.godot file.\n\nOptions:\n\n-h/--help             -- Display this help message.\n-o/--output-directory -- directory path to output the documentation into.\n-d/--directory        -- Name of a directory to find files and generate the code reference in the Godot project.\n                         You can use the option multiple times to generate a reference for multiple directories.\n-f/--format           -- Either `markdown` or `hugo`. If `hugo`, the output document includes a TOML front-matter\n                         at the top. Default: `markdown`.\n-a/--author           -- If --format is `hugo`, controls the author property in the TOML front-matter.\n\n\nUsage example:\n\ngenerate_reference ~/Repositories/other/nakama-godot/project/ -o export-nakama -d addons\n\nThis command walks files in the res://addons directory of the Godot Nakama project, and converts it\nto markdown files output in ./export-nakama.\n```\n\nTo use them:\n\n- You need to clone this repository or download the source code from a [stable release](https://github.com/GDQuest/gdscript-docs-maker/releases).\n- You need `godot` to be available on the [system PATH variable](\u003chttps://en.wikipedia.org/wiki/PATH_(variable)\u003e).\n\n## Hugo output\n\nYou can output markdown files for [hugo](https://gohugo.io/), the static website engine.\n\nTo do so, call GDScript docs maker with the `--format hugo` option. You can use two extra flags with this:\n\n```bash\n--date YYYY-MM-DD, the date in iso format, if you want the documents to have a date other than today. Default: datetime.date.today()\n--author author_id, the id of the author on your hugo website, to assign an the author for the documents. Default: \"\"\n```\n\nHere's how I generate the Godot Steering Toolkit's documentation. This command outputs the class reference straight into the website:\n\n```bash\npython3 -m gdscript_docs_maker $HOME/Repositories/godot-steering-toolkit/project/reference.json --format hugo --author razoric --path $HOME/Repositories/website/content/docs/godot-steering-toolkit/reference/classes/\n```\n\n# The manual way\n\nIf you want to generate the JSON and convert it manually, there are three steps involved:\n\n1. Copying the GDScript files to your Godot project:\n    - `./godot-scripts/Collector.gd` and `./godot-scripts/ReferenceCollectorCLI.gd` or `./godot-scripts/ReferenceCollectorCLI.gd` for Godot 3\n    - `./godot-scripts/CollectorGd4.gd` and `./godot-scripts/ReferenceCollectorCLIGd4.gd` or `./godot-scripts/ReferenceCollectorCLIGd4.gd` for Godot 4\n2. Running the GDScript code with Godot, either from the editor (`ReferenceCollector.gd` / `ReferenceCollectorGd4.gd`) or by calling Godot from the command line (`ReferenceCollectorCLI.gd` / `ReferenceCollectorCLIGd4.gd`).\n3. Running `gdscript_docs_maker` on the reference.json file that Godot generated in the previous step.\n\n\u003c!-- TODO: turn into a note block on the website. --\u003e\n\n**Note**: to parse and collect data from GDScript code, we rely on the GDScript language server that's new in Godot 3.2.\n\n### Converting JSON\n\nCall the `gdscript-docs-maker` package directly using the `python -m` option:\n\n```\nUsage: gdscript_docs_maker [-h] [-p PATH] [-v] [--dry-run] files [files ...]\n\nMerges or converts json data dumped by Godot's GDScript language server to\ncreate a code reference.\n\npositional arguments:\n  files                 A list of paths to JSON files.\n\noptional arguments:\n  -h, --help            Show this help message and exit.\n  -p PATH, --path PATH  Path to the output directory.\n  -v, --verbose         Set the verbosity level. For example, -vv sets the\n                        verbosity level to 2. Default: 0.\n  --dry-run             Run the script without creating\n                        files and folders. For debugging purposes.\n```\n\nThe program takes a list of JSON files. For example, we generate the code reference of our AI framework [Godot Steering Toolkit](https://github.com/GDQuest/godot-steering-toolkit/) like so with the shell:\n\n```fish\npython -m gdscript-docs-maker ~/Repositories/godot-steering-toolkit/src/reference.json\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgdquest%2Fgdscript-docs-maker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgdquest%2Fgdscript-docs-maker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgdquest%2Fgdscript-docs-maker/lists"}