{"id":14961812,"url":"https://github.com/douglaswebster/gdscript-to-restructured","last_synced_at":"2026-02-07T09:31:34.160Z","repository":{"id":52542295,"uuid":"345094461","full_name":"DouglasWebster/gdscript-to-restructured","owner":"DouglasWebster","description":"Create reStructured text files from the JSON files created using generate-reference from gdscript-docs-maker ","archived":false,"fork":false,"pushed_at":"2022-10-04T08:36:09.000Z","size":1310,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-07-12T10:05:55.934Z","etag":null,"topics":["documentation-tool","gdscript","gdscript-docs-maker","godot","restructured-text","sphinx-documentation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DouglasWebster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-06T12:59:29.000Z","updated_at":"2023-08-08T11:05:26.000Z","dependencies_parsed_at":"2022-08-29T23:22:33.200Z","dependency_job_id":null,"html_url":"https://github.com/DouglasWebster/gdscript-to-restructured","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DouglasWebster/gdscript-to-restructured","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DouglasWebster%2Fgdscript-to-restructured","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DouglasWebster%2Fgdscript-to-restructured/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DouglasWebster%2Fgdscript-to-restructured/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DouglasWebster%2Fgdscript-to-restructured/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DouglasWebster","download_url":"https://codeload.github.com/DouglasWebster/gdscript-to-restructured/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DouglasWebster%2Fgdscript-to-restructured/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268339661,"owners_count":24234560,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-tool","gdscript","gdscript-docs-maker","godot","restructured-text","sphinx-documentation"],"created_at":"2024-09-24T13:27:48.835Z","updated_at":"2026-02-07T09:31:34.123Z","avatar_url":"https://github.com/DouglasWebster.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GDScript reStructuredText Docs Maker\n\nThis is a tool to document your Godot gdscript files into ***re*****Structured*****Text*** (..rst) files and to create an index of the generated files if required.\n\nThe code is based on the [gdscript-docs-maker code](https://github.com/GDQuest/gdscript-docs-maker) from [**GDQuest**](https://www.gdquest.com/) and, in as far as the initial stages of the conversion are concerned, it is a direct copy of their code with a few notable exceptions:\n- This version only provides ***re*****Structured*****Text*** (.rst) output - if you require markdown or Hugo output then please follow the above link and use the original version.\n- As there is no facility to create markdown or Hugo files the `-f/--format` and  `-a/--author` options in the original are no longer available.\n- Multi-line comments in the code are concatenated to single line comments unless there are multiple  line breaks, in which case the line breaks are preserved.  This is to give, hopefully, a better flow of the description text.\n\n## Installation\n\nYou should install gdscript2rest from [PyPI](https://pypi.org) with \n\n`python -m pip install gdscript2rest` \n ## Additional requirements\n\nIn order to make the links from the Godot class names to the Godot API help files a link file has to be created and available to in the working directory of the program.  This can be accomplished by installing a small utility [godot-api-refs](https://pypi.org/project/godot-api-refs/) and running it in from the current working directory.\n\n---\n## Usage\n\nThere are 2 scripts in the repository:\n* generate_reference     - for Linux and Mac (though the script is untested on a Mac)\n* generate_reference.bat - for windows in a cmd prompt (it doesn't seem to work in a powershell terminal)\n\nBoth scripts will generate the documentation in the desired folder.\n\n## Linux and Mac\n\nRunning `./generate_reference -h` in a terminal will give the following\n\n```\n    Generate reST file references from GDScript\n    Usage:\n    generate_reference $project_directory [options]\n\n    Required arguments:\n\n    $project_directory -- path to your Godot project directory.\n\n    This directory or one of its subdirectories should contain a project.godot file.\n\n    Options:\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\n                            the Godot project. You can use the option multiple times to generate\n                            a reference for multiple directories.\n    -i/                     Create a reST index file in the output directory that references all\n                            the API reST files.\n    -v/--verbose            Set the verbosity level. For example -vv sets verbosity to level 2.\n                            Defalt: 0.\n    -V/--version            Print the version number and exit.\n    --doc-version           Set the document version number if there is no version set in the\n                            JSON file. Defaults to 0.0.0\n\n    Usage example:\n\n    generate_reference ~/Repositories/other/nakama-godot/project/ -o docs/source/api/addons \n              -d addons -i -v --doc-version 0.1.5\n\n    This command walks files in the res://addons directory of the Godot Nakama project, and \n    stores the resultant code dump in the docs/source/api/addons directory of the current pwd.\n    It then invokes gdscript2rest and creates the reST files in the same directory, detailing\n    each file processed, creating an index file and setting the version to 0.1.5\n```\n\n## Windows\n\nRunning `generate_reference.bat -h` in a cmd window will give the following\n\n```\nCreates and parses reference documentation for a GDScript based projects.\n\ngenerate_reference $Path [-p dest] [-v | -vv] [--dry-run] [-i] [-V] [--doc-version]\n\n  $Path  The path to the Godot project.   \n\n  -h --help           Display this help file.\n\n  -p --path dest      Path to the output directory.\n    \n  -v --verbose        Set the verbosity level. For example, -vv sets the verbosity\n                      level to 2.\n\n  --dry-run           Run the script without actual rendering or creating files\n                      and folders. For debugging purposes\n\n  -i --make-index     If this flag is present, create an index.md page with a table\n                      of contents.\n\n  -V --version        Display the version of the gdscript2rest program\n\n  --doc-version       Set the version number shown in the documentation.  Defaults to\n                      0.0.0 (currently Godot does not output a version number).\n```\n\nThe commands are the same as the Linux/Mac version except there is no option to cherry pick the directories in the Godot project.  This involves changing the ReferenceCollectorCLI.gd file on the fly which I something I don't know how to do in a batch file.\n\n---\n## Detailed explanation \n\nThe generation of the ***re*****Structured*****Text*** files is a two step process.\n\n1. Create a JSON file that contains all the information extracted from your Godot project script files.\n2. Turn each of the separate classes in the JSON file that contains a class_name qualifier into a separate ***re*****Structured*****Text*** file.\n\nThe above script automates the two processes which can be accomplished individually by: \n## Stage 1 - Create the JSON file\n\nThis is done in the `generate_reference` script by:\n\n1.  Copying the GDScript files `./godot-scripts/Collector.gd` and `./godot-scripts/ReferenceCollectorCLI.gd` or `./godot-scripts/ReferenceCollectorCLI.gd` to your Godot 3.3 project.\n2. Running the GDScript code in the project with Godot\n3. Removing the godot-scripts files that were initially copied over.\n\nThis leaves a copy of the ***reference.json*** file in the Godot project directory.\n\n(The $project_directory and -d/--directory options are applicable to this stage)\n\nA fuller explanation of this stage is detailed at  [gdscript-docs-maker code](https://github.com/GDQuest/gdscript-docs-maker) \n\n## Stage 2 - Create the reStructuredText documents\n\nThis is done in the `generate_reference` script by:\n\n1. Moving the ***reference.json*** file from the Godot project directory to the output_directory, creating the output_directory if required\n2. Running `python -m gdscript2rest $ReferenceFile [options]` where $ReferenceFile is the file created in part 1 and the options are the remaining unused options.  \n\n\n## Detailed explanation of the gdscritp2rest python module\n\n`gdscript2rest` is a python module that scans the reference.json file and creates individual reStructuredText files for each individual class enumerated in the file.  \n\nThe individual files have full linkages to:\n\n* code inside the file i.e variable use in a function declaration to the variable declaration\n* code in the same project i.e the parent class in a state machine.\n* the Godot help system.  i.e. the declaration Extends: Node2D, the Node2d links to the Godot help file\n\n\n\nIf you run \n```\npython -m gdscript2rest -h\n```\n\nit will display the following which lists the options available to the program.\n```\nusage: gdscript2rest [-h] [-p PATH] [-i] [-v] [--dry-run] [-V] files [files ...]\n\nConverts JSON data dumped by Godot's GDScript language server to create .rst files for \nuse with Sphinx.\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  -i, --make-index      If this flag is present, create an index.rst page with a table of contents.\n  -v, --verbose         Set the verbosity level. For example -vv sets verbosity to level 2. \n                        (Default: 0.)\n  --dry-run             Run the script at max verbosity without creating files.\n                        (For debugging purposes.)\n  -V, --version         Print the version number and exit,\n --doc-version DOC_VERSION\n                        Set the document version number if there is no version set in the JSON file. \n                        Defaults to 0.0.0\n ```\n\nA fuller explanation of the options is:\n\n* files :-\u003e this is a list of files generated by ***generate-reference*** that is used as the input to the program\n* -h --help :-\u003e prints out the above usage statement and exits.\n* -p PATH, --path PATH :-\u003e outputs the reStructuredText files to PATH, this can be either an absolute or relative path\n* -i :-\u003e Creates an index file ***index.rst***.  This file is a very basic file with a single toctree entry that globs all the files in its directory\n*  -v, --verbose :-\u003e Prints out information as the program progresses.  Not over helpful but could aid in finding problems.\n* --dry-run             Run the script at max verbosity without creating files. (For debugging purposes.)\n*  -V, --version         Print the version number and exit,\n* --doc-version DOC_VERSION :-\u003e Unless I'm missing something Godot doesn't currently have the facility to store a version number so this gives the option to set the version number manually.  If not used the version number defaults to 0.0.0\n\n---\n## Further Information\n\nFor additional information and a brief tutorial on how to use the ***re*****Structured*****Text*** files to create a Sphinx documents site see the [Wiki](https://github.com/DouglasWebster/gdscript-to-restructured/wiki) section of this repository.\n\n## Acknowledgements\n\nMy thanks to the people at [**GDQuest**](https://www.gdquest.com/) for providing the initial program from which this was derived and to the people at [Godot](https://godotengine.org/) for putting all there hard work out there for us to use.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdouglaswebster%2Fgdscript-to-restructured","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdouglaswebster%2Fgdscript-to-restructured","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdouglaswebster%2Fgdscript-to-restructured/lists"}