Creating a local Sphinx document web site

How to create an HTML site using gdscript2rest and Sphinx

reStructuredText is a markup language primarily created for documenting python code but is now widely used for many diverse projects.

Sphinx is a document generator tool that can take the reStructuredText text files and turn them into professional looking documents in a variety of formats; html, pdf. latex etc...

Sphinx should be installed following these instructions Installing Sphinx as the methods vary greatly by operating system and by type.

In this example I am using the godot-design-patterns sample from GDQuest as a test project.

Once it is installed then I recommend creating a separate docs folder to hold the source documents and the output for your project documentation. In a terminal change to your newly created docs folder and run

shpinx-quickstart

answering the questions asked (I normally opt for a separate source and build directories when asked as I find it easier to for things like .gitignore). This will give you the basic scaffolding for a Sphinx project.

Once the basic scaffolding is done you should have the following folder structure:

sphinx-test/
┗ docs/
  ┣ source/
  ┃ ┣ _static/
  ┃ ┣ _templates/
  ┃ ┣ conf.py
  ┃ ┗ index.rst
  ┣ Makefile
  ┗ make.bat

First run

godot-api-refs

to generate the godot_api_calls.json which is required to create the reference links to the Godot help files for the Godot classes. This should only need to be run once per project.

Then create the reference.json file(s) required for your project with

./generate-reference path-to-your-godot-project -o docs/source/api -i

The -i will overwrite the index file with one that globs all the created API files. This should give the following files structure.

sphinx-test/
┣ docs/
┃ ┣ source/
┃ ┃ ┣ _static/
┃ ┃ ┣ _templates/
┃ ┃ ┣ BatteryEntity.rst
┃ ┃ ┣ conf.py
┃ ┃ ┣ index.rst
┃ ┃ ┣ Player.rst
┃ ┃ ┣ PlayerNoStates.rst
┃ ┃ ┣ PlayerState.rst
┃ ┃ ┣ PowerReceiver.rst
┃ ┃ ┣ PowerSource.rst
┃ ┃ ┣ PowerSystem.rst
┃ ┃ ┣ reference.json
┃ ┃ ┣ State.rst
┃ ┃ ┗ StateMachine.rst
┃ ┣ Makefile
┃ ┗ make.bat
┣ godot_api_calls.json
┗ reference.json

Change into the docs directory and run make html which will create the html files for your project documentation and give something like the following (the extraneous files in sources, _static etc, have been omitted):

sphinx-test/
┣ docs/
┃ ┣ build/
┃ ┃ ┣ doctrees/
┃ ┃ ┗ html/
┃ ┃   ┣ _sources/
┃ ┃   ┣ _static/
┃ ┃   ┣ .buildinfo
┃ ┃   ┣ BatteryEntity.html
┃ ┃   ┣ genindex.html
┃ ┃   ┣ index.html
┃ ┃   ┣ objects.inv
┃ ┃   ┣ Player.html
┃ ┃   ┣ PlayerNoStates.html
┃ ┃   ┣ PlayerState.html
┃ ┃   ┣ PowerReceiver.html
┃ ┃   ┣ PowerSystem.html
┃ ┃   ┣ PowerSource.html
┃ ┃   ┣ State.html
┃ ┃   ┣ search.html
┃ ┃   ┗ searchindex.js
┃ ┃   ┣ StateMachine.html
┃ ┣ source/
┃ ┃ ┣ _static/
┃ ┃ ┣ _templates/
┃ ┃ ┣ BatteryEntity.rst
┃ ┃ ┣ conf.py
┃ ┃ ┣ index.rst
┃ ┃ ┣ Player.rst
┃ ┃ ┣ PlayerNoStates.rst
┃ ┃ ┣ PlayerState.rst
┃ ┃ ┣ PowerReceiver.rst
┃ ┃ ┣ PowerSource.rst
┃ ┃ ┣ PowerSystem.rst
┃ ┃ ┣ reference.json
┃ ┃ ┣ State.rst
┃ ┃ ┗ StateMachine.rst
┃ ┣ Makefile
┃ ┗ make.bat
┣ godot_api_calls.json
┗ reference.json

If you now open the index.html page in a browser you should have a working copy of your API documentation but the external links are showing something like Extends: :godot_class:`Node2D <node2d> and don't do anything when clicked. There will also have been several warning messages during the build. This is because as it stands at the moment Sphinx does not know how to handle the external links. In order for the external links to be active the conf.py file in the source dir has to be upgraded.

In conf.py change

extensions = [
]

to

extensions = [
        "sphinx.ext.extlinks"
]

This enable external links using a shorthand link name. Now add the following to conf.py bellow the extension section to tell Sphinx where the shorthand name :godot_class: points to.

 extlinks = {
    'godot_class' : 
        ('https://docs.godotengine.org/en/stable/classes/class_%s.html', '')
}

Now, if you do make clean to get rid of the bad build followed by make html you should have a working copy of your documentation with all the external links active.