Setting up conf.py
Setting up conf.py
to give the look and feel of the Godot Documentation is fairly complex so I will
just go over the important parts. A full conf.py file is available in the appendix
and can be copied over to give you the correct set up. Just remember to change the Project information
section to your requirements.
Basic changes
Changing the theme
The first thing is to change the theme this is done by setting
html_theme = 'sphinx_rtd_theme'
This will give it the general appearance of the Godot help files and your preview should change to match.
Enabling external links
After this we can set up Sphinx so that the documentation can link to external web pages. This is accomplished by:
Adding an extension to the extensions array:
extensions = [ "sphinx.ext.extlinks" # to generate external links ]
Setting up the godot_class to point to the correct location (the %s is a placeholder which will be replaced by the appropriate Godot class name):
extlinks = { 'godot_class' : ('https://docs.godotengine.org/en/stable/classes/class_%s.html', '') }
Finalising the look and feel
The above will give the basic functionality and if all you are creating is a basic document then that may well be sufficient. There are still differences between this and the Godot look and feel. In order to more closely approach the Godot look then a custom .css file has to be installed and Sphinx instructed to make use of it.
You can find an up to date copy of the .css file required at Godot cusom.css. A copy of this file at the time of writing is in Appendix B - custom css file
Create a new folder in the _static
folder called css
and store the custom.css
file in there. Then
alter conf.py
to include:
# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
"css/custom.css",
]
Additional enhancements
Correctly highlighting GDScript code snippets
If you want to see any gdscript code snippets highlighted correctly then they have to be shown in a
..code:: gdscript
block and will display like this:
# The model of the battery used in the
# simulation.
#
# .. warning:: This mode isn't at all accurate
# and should not be used for any practicle
# projects.
class_name BatteryEntity
extends Node2D
## Total amount of power the battery is able to hold
export var max_storage := 1000.0
## Actual amount of power currently in the battery
var stored_power := 0.0 setget _set_stored_power
onready var receiver := $PowerReceiver
onready var source := $PowerSource
onready var indicator := $Indicator
func _set_stored_power(value: float) -> void:
stored_power = value
An undefined lexing style ..code::
block will not highlight correctly and display like this:
# The model of the battery used in the
# simulation.
#
# .. warning:: This mode isn't at all accurate
# and should not be used for any practicle
# projects.
class_name BatteryEntity
extends Node2D
## Total amount of power the battery is able to hold
export var max_storage := 1000.0
## Actual amount of power currently in the battery
var stored_power := 0.0 setget _set_stored_power
onready var receiver := $PowerReceiver
onready var source := $PowerSource
onready var indicator := $Indicator
func _set_stored_power(value: float) -> void:
stored_power = value
If you want your code snippets to default to the gdscript lexer then add the following to the conf.py
file:
# Pygments (syntax highlighting) style to use
pygments_style = "sphinx"
highlight_language = "gdscript"
Adding a logo
You can have a logo for the document that displays at the top of the sidebar. For my documents I
normally create an images
folder and store all any images required in the document there. Suppose you
have an image in this folder called logo.png
then you can select this as the logo with:
html_logo = 'images/logo.png'
Advanced options
There are many more options available for fine tuning the look and feel of your document but the above will give you a look not dissimilar to the Godot documentation. If you want to see the full range of options available then check out the Sphinx configuration documentation, the sphinx-rtd-theme documentation and the Godot Document source.