- how to generate HTML documentation using sphinx for gdscipt files
- write documentation comments
- export XML class references using --doctool --gdscript-docs
- generate RST files using make_rst.py
- modify script
- generate HTML documentation using sphinx
- install extension
- install theme
The first step is to document your scripts according to this doc page: https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_documentation_comments.html
GDScript documentation comments are generally put after "##" immediately preceding the element you are documenting
In order to export the class references based on the documentation comments created in step 1, we need to be able to use the Godot command line tool. This doc page covers command line use for Godot: https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html
If you didn't install Godot with scoop, and you want to make your existing installation work with the command line, this is how you do it:
First, locate where your Godot executable is (for me this is C:\Program Files\Godot):
Next, add this directory to your PATH environment variable:
Finally, rename the godot executable to "godot.exe". This allows you to access command line tools by just typing "godot" from any directory.
You can verify this worked by running godot --version from the command line
Now that that godot works over the command line, we will use the --doctool command to generate the XML files. --doctool is what is used to create the engine documentation, and by default will output an XML file for every class in the engine. However, if you use the --gdscript-docs command with it, it will output XML files only for gdscript files found at the path you provide.
The full command we will run is godot --doctool <path1> --gdscript-docs <path2>
godotaccesses the godot command line tool--doctool <path1>tells doctool to output the XML files to the location at<path1>--gdscript-docs <path2>tells doctool to only generate XML files for scripts found in the location<path2>
and can be whatever you want them to be. but I will explain how I do it, to minimize confusing paths
First, navigate to whatever folder contains the scripts that you want to generate documentation for in your file explorer. For this example, I have all of the scripts in the project folder Documents\Games\Godot\TestGrounds:
Next, create a folder the XML files will be saved to. Here I made the folder doc_export:
Next, open the command prompt and navigate to the folder that contains your scripts (Documents\Games\Godot\TestGrounds):
Finally, we can run our command,godot --doctool <path1> --gdscript-docs <path2> where <path1> is doc_export and <path2> is the current directory, or .
That means the final command, for the example, is godot --doctool doc_export --gdscript-docs .
When it runs, it will create a headless session of godot (i think) so just give it a few seconds, and then you can exit using ctrl+C in the command line.
If it was successful, you should have an XML file for each script in your doc_export folder:
If you have made it this far, you can use my other tool to view and export a simplified version of docs from the XML files directly: https://github.com/InfernalWAVE/gdscript-xml-docviewer
For interactive docs, we will need to do a bit more.
The XML files we generated in step 3 are "class references" for each script that we documented. We can use these class references to generate reStructuredText (RST) files using the make_rst python tool included in the engine source. The file itself can be found here: https://github.com/godotengine/godot/blob/master/doc/tools/make_rst.py
However, in order to run the make_rst.py tool, you need to clone the whole godot repo. This is because make_rst.py depends on other parts of the repo, specifically the "import version".
Additionally, we will need to make 2 adjustments to the make_rst.py script once the repo is downloaded. The adjusted file is also available in this repo if you would rather just replace it.
Additionally, additionally, you will need python installed and added to your path. There are several tutorials for how to accomplish this online. You can verify your python is ready to use by running python --version from your command prompt:
Now that we have verified python is ready to use, we need to download the godot repo. You can do this using git, or you can go to the following link and click Code > Download Zip. https://github.com/godotengine/godot/tree/master
If you downloaded the .zip, extract the folder to a convenient location. For this example I will be using Documents\godot-source
Once the godot folder is extracted and ready, go to godot/doc/tools this is where the make_rst.py tool is that we need to modify.
When the doctool generates the XML files for gdscript files, the names (and inherits from extended gdscripts) end up with quotation marks and relative filepath artifacts:
These weird strings cause errors when we try to run make_rst.py. So you can manually remove the characters, or we can modify the make_rst.py tool to clean the strings automatically as it parses the XML.
Either replace make_rst.py with the file in this repo, or make the following changes to the file. The changes are to the parse_class method in the State class. :
These changes just strip the illegal characters from the name and inherits attributes as it reads them from the XML. NOTE: THERE MAY BE A BETTER WAY TO DO THIS, IDK
Either way, once the changes have been made, we are almost ready to generate the RST files!
Before we begin, we need to set up folders for our inputs to and outputs from the make_rst.py tool. So navigate to the folder that contains make_rst.py:
Create two folders in this location, one for input files and one for output files. For this example, I will be naming them doc_input and doc_output:
Copy the XML class references we generated earlier into the doc_input folder
Okay, now we are finally ready to run this make_rst.py script!
From the command prompt, navigate to the folder that contains make_rst.py:
The command we are going to run is python make_rst.py <path1> --output <path2>
python make_rst.pyaccesses python from the command line and executes the script<path1tells the script where to scan for XML files as input--output <path2>tells the script where to output the RST files it generates
So for this example, the final command is python make_rst.py doc_input --output doc_output:
Don't panic about the errors! What is happening is that the script is trying to link to class references for things like Variant or float, since those are types that were used in the scripts. If you want to, you can include class references for those items by grabbing the XML files from https://github.com/godotengine/godot/tree/master/doc/classes
However, as you add class references from the engine, you will get more and more of these unresolved type errors. This is because the references you add make their own references to even more classes, and it is a kind of cascading effect. The only way to get the RST files to generate without error is to include literally all of the class references for the engine (which I did just to check, it works). The doc/classes section of the repo also does not contain all of the class references for the engine. Some of them are spread out, in their own doc_classes folder (like GridMap for example: https://github.com/godotengine/godot/blob/master/modules/gridmap/doc_classes/GridMap.xml).
Anyways, if it was successful, you should have RST files in your doc_output folder:
Congratulations if you made it this far! Now we just need to run these RST files through sphinx to get our documentation.
Install sphinx according to their installation instructions: https://www.sphinx-doc.org/en/master/usage/installation.html
Since we know python is ready to use in the command prompt, we can use pip to install it with python -m pip install sphinx
We will also need an extension for sphinx that the godot documentation expects, called sphinx-tabs: https://sphinx-tabs.readthedocs.io/en/latest/
We can install sphinx-tabs with python -m pip install sphinx-tabs
This isn't mandatory, but we will install the sphinx theme that godot uses as well by ReadTheDocs: https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/
We can install the ReadTheDocs theme with python -m pip install sphinx-rtd-theme
Once everything is installed, we need to make a directory for sphinx to work in. For this example it will be Documents\docs_test:
From the command prompt, navigate to this folder:
Run the sphinx-quickstart command in the command prompt to initialize the documentation project in the current folder, follow the docs here: https://www.sphinx-doc.org/en/master/usage/quickstart.html
When you run the command, it will automatically select the folder you are currently in as the root folder, and begin asking you setup questions:
I choose yes to separate "source" and "build", this will create two separate folders for us to use for input and output in the root. Then it will ask ask for a project name, author name, and release version:
I chose "gdscript-doc-tutorial", my name, and 0.0.1. Then it asks about a language:
Since I am writing this in English, and it defaults to English, I just hit enter. This finally initializes the project and creates some files in the docs_test folder:
Before building our documentation, we need to enable the extension and theme that we installed earlier. To do this, we need to edit a file in docs_test\source:
conf.py defines configuration information for the documentation when sphinx goes to build it. So open conf.py in a text editor:
When the project is initialized, it creates some basic templates for us to use in conf.py. We will add the sphinx-tabs extension to the extensions array and we will add the theme in the html-theme variable. The updated file should look like the following:
The lines exactly are:
extensions = ['sphinx_tabs.tabs']
html_theme = 'sphinx_rtd_theme'
Save the updated conf.py file.
Now we need to add all of the RST files we generated earlier to the docs_test\source folder:
When you add the files, windows will warn you that index.rst already exists in the destination, just replace it. The make_rst.py tool created the index.rst we want earlier.
Now that conf.py has been configured, and the source RST files have been added, we are ready to build the documentation!
From the command prompt, navigate to the docs_test folder:
The command we are going to run is sphinx-build -M html <path1> <path2> where
sphinx-build -M htmluses the sphinx-build tool to create HTML documentation using "make mode"<path1>is the location sphinx-build will use as the input source<path2>is the location sphinx-build will save the HTML documentation to
So the final command is sphinx-build -M html source build:
Don't worry about the warning(s)! I think they are related to the "unable to resolve type" errors earlier when we were generating the RST files, and it just depends on how many class references from the engine you want to include!
If it was successful, you should have an HTML project in your docs_test\build\html folder:
You should be able to open index.html in your browser, and browse your docs! That's it!
