create_godot_clone

Making the Sphinx Document Look like Godot Help

The Sphinx document created by following the basic Sphinx tutorial gives a document with the look and feel of the default Sphinx theme (at the time of writing it is Alabaster). Whilst this is a perfectly acceptable basic theme, one of my primary aims when converting the GDQuest document generator was to produce documentation with the look and feel of the Godot Document website.

The following two screen captures showing how it looks with the godot-design-patterns code from GDQuest.

This proved to be not too arduous a task as the Godot Docs repository is open source under the MIT licence so it was just a case of tweaking my conf.py file to match and to copy over the css and js.

The main repository has a bare bones docs folder which can be copied 'as is' to provide the required look and feel.

For those interested I'll detail the changes made as you may want to cherry pick parts for your project without copying the entire docs layout.

The conf.py file

import sphinx_rtd_theme  # This is the base theme for the project
import os                # We need access to the operating system 
import sys               # and the system calls.
.
.
# project, copyright, author, version and realease are free settings for the user.
.
.
pygments_style = 'sphinx' lexer for code highlighting
.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 
.
.
needs_sphinx = '3.0'     # minimum sphinx version

# add the local _extensions folder to the system path so
# the required extensions can be found.

sys.path.append(os.path.abspath("_extensions")) 

extensions = [
    'sphinx_tabs.tabs',         # for tabbed pages if required
    "notfound.extension",       # to generate your own 'page not found' page
    "sphinx.ext.extlinks"       # to genreate external links
]
.
.
.
# this is the bit that allows a shortcut to the godot help files.
# note it points to the stable documentation - change the word stable to link to documentation version you want.
# i.e. https://docs.godotengine.org/en/latest/classes/class_%s.html' to reference the latest doc versions.

extlinks = {            
    'godot_class' : 
        ('https://docs.godotengine.org/en/stable/classes/class_%s.html', '')
}
.
.
.
# Custom 4O4 page HTML template.
# https://github.com/readthedocs/sphinx-notfound-page
notfound_context = {
    "title": "Page not found",
    "body": """
        <h1>Page not found</h1>
        <p>
            Sorry, we couldn't find that page. It may have been renamed or removed
            in the version of the documentation you're currently browsing.
        </p>
        <p>
            If you're currently browsing the
            <em>latest</em> version of the documentation, try browsing the
            <a href="/en/stable/"><em>stable</em> version of the documentation</a>.
        </p>
        <p>
            Alternatively, use the
            <a href="#" onclick="$('#rtd-search-form [name=\\'q\\']').focus()">Search docs</a>
            box on the left or <a href="/">go to the homepage</a>.
        </p>
    """,
}


# Projects can be published to readthedocs in which case the following will apply

# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get("READTHEDOCS", None) == "True"

if not on_rtd:
    notfound_urls_prefix = ''

if not os.getenv("SPHINX_NO_GDSCRIPT"):
    extensions.append("gdscript")

# if not os.getenv("SPHINX_NO_SEARCH"):
#     extensions.append("sphinx_search.extension")

if not os.getenv("SPHINX_NO_DESCRIPTIONS"):
    extensions.append("godot_descriptions")

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# You can specify multiple suffix as a list of string: ['.rst', '.md']
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_encoding = 'utf-8-sig'

# The master toctree document - should be in the same folder a conf.py unless you 
# really know what you are doing.

master_doc = 'index'

# Parse Sphinx tags passed from RTD via environment
env_tags = os.getenv("SPHINX_TAGS")
if env_tags is not None:
    for tag in env_tags.split(","):
        print("Adding Sphinx tag: %s" % tag.strip())
        tags.add(tag.strip())  # noqa: F82

supported_languages = {
    "en": "Godot Engine (%s) documentation in English",
}

language = os.getenv("READTHEDOCS_LANGUAGE", "en")
if not language in supported_languages.keys():
    print("Unknown language: " + language)
    print("Supported languages: " + ", ".join(supported_languages.keys()))
    print(
        "The configured language is either wrong, or it should be added to supported_languages in conf.py. Falling back to 'en'."
    )
    language = "en"

is_i18n = tags.has("i18n")  # noqa: F821

exclude_patterns = ["_build"]

# fmt: off
# These imports should *not* be moved to the start of the file,
# they depend on the sys.path.append call registering "_extensions".
# GDScript syntax highlighting
from gdscript import GDScriptLexer
from sphinx.highlighting import lexers

lexers["gdscript"] = GDScriptLexer()
# fmt: on

smartquotes = False

# Pygments (syntax highlighting) style to use
pygments_style = "sphinx"
highlight_language = "gdscript"

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".

html_static_path = ['_static']

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
    "css/custom.css",
    "css/my.css"
]

html_js_files = [
    "js/custom.js",
]

html_theme_options = {
    'logo_only': True,
    'collapse_navigation': False
}

# Either change this to point to your logo or store your logo in the docs/source folder under this name
html_logo = "docs_logo.png" 

latex_elements = {
    'extraclassoptions': 'openany',
    'preamble': r'''
\usepackage{subfig}
\usepackage{graphicx}
''',
    'papersize': 'a4paper'
}

The module requires several other python modules to be installed and these are listed in the prerequisites.

The extensions

There are two extensions in the _extensions folder that are required:

• gdscript.py - this is the lexer that is required by Pygments
• godot_descriptions.py - seems to do special formatting of code I think

Static files

These hold the css and js files for refining the look and feel of the document

CSS files

• custom.css - This give the look and feel for the website. I have commented out a part of the code that distinguishes between internal and external links (lines 276 - 310). This was putting a ref badge against the Godot help links which I didn't like. If you want this distinction then just uncomment those lines.

• my.css - I've overridden .bolditalic style to one more pleasing to me. Again, if you don't like it then just get rid of it.