-
Notifications
You must be signed in to change notification settings - Fork 0
create ref json
The generation of the reStructuredText text files can be accomplished in one pass using either of the script files generate_references or generate_references.bat.
I use the following structure for my documentation project folder which will be the basis for this and following wiki pages. You are, of course, free to pick any structure you want and amend any instructions accordingly.
sample-doc-project/
┣ docs/
┣ godot-scripts/
┃ ┣ Collector.gd
┃ ┣ README.md
┃ ┣ ReferenceCollector.gd
┃ ┗ ReferenceCollectorCLI.gd
┣ .gitignore
┣ LICENSE
┣ README.md
┣ generate_reference
┗ generate_reference.bat
Where the godot-scripts folder and generate-reference are copied either from this repository.
The godot-scripts folder holds the scripts that will be temporarily imported into your Godot project to create the dump of the required project GDScript files.
The generate-reference is a script file that that will create the reference.json file that is the basis for creating the reStructuredText documentation.
See the README file for instructions on using the script files
The -o option and -d options I find useful for splitting up the code when used together. For example, say in your game you have all the enemies in a folder called baddies and all main characters in a folder called goodies then running:
generate_reference $GodotGameProjectDirectory -o docs/source/api/baddies -d baddies -i
followed by:
generate_reference $GodotGameProjectDirectory -o docs/source/api/goodies -d goodies -1
Will give the following folder structure
sample-doc-project/
┣ docs/
┃ ┗source/
┃ ┗ api
┃ ┣ baddies
┃ ┃ ┣ reference.json
┃ ┃ ┣ index.rst
┃ ┃ ┣ .
┃ ┃ ┣ .
┃ ┃ ┣ .
┃ ┃ ┗ (all your baddies .rst files)
┃ ┗ goodies
┃ ┣ reference.json
┃ ┣ index.rst
┃ ┣ .
┃ ┣ .
┃ ┣ .
┃ ┗ (all your goodies .rst files)
┣ godot-scripts/
┃ ┣ Collector.gd
┃ ┣ README.md
┃ ┣ ReferenceCollector.gd
┃ ┗ ReferenceCollectorCLI.gd
┣ .gitignore
┣ LICENSE
┣ README.md
┗ generate_reference
With distinct references to your goodies and baddies scripts.
Running generate_reference without any options will create a reference.json in the current working directory of all the GDScript files in the project.
The generate_reference.bat does not have the -o option and the script is unable to filter Godot folders. This means the whole Game project documentation is recreated with each use.
To create the a similar output to the above but with only one level of API documentation you would use
generate_reference $GodotGameProjectDirectory -o docs/source/api -i
Which will result in the following
sample-doc-project/
┣ docs/
┃ ┗source/
┃ ┗ api
┃ ┣ reference.json
┃ ┣ index.rst
┃ ┣ .
┃ ┣ .
┃ ┣ .
┃ ┗ (all your game .rst files)
┣ godot-scripts/
┃ ┣ Collector.gd
┃ ┣ README.md
┃ ┣ ReferenceCollector.gd
┃ ┗ ReferenceCollectorCLI.gd
┣ .gitignore
┣ LICENSE
┣ README.md
┗ generate_reference
NOTE: this should be run in a cmd window; using a Powershell window gives all sorts of error messages.
(I'm not a big fan of windows so don't really know batch programming to any depth hence this is my best effort at creating a simple one step interface. Anyone with the ability who want's to take it on and polish it up i.e get it working reliably, please feel free.)
If all you want is the reference.json output then I suggest using gdscripts-docs-maker which has full instructions on creating reference files, as well as generating markdown and Hugo files if that type of output is required.
If you use gdscript-docs-maker to create the reference.json file then see using gdscript2rest on how to proceed.