-
-
Notifications
You must be signed in to change notification settings - Fork 3k
/
conf.py
323 lines (262 loc) · 11.9 KB
/
conf.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
# -*- coding: utf-8 -*-
#
# Godot Engine documentation build configuration file
import sphinx
import sphinx_rtd_theme
import sys
import os
# -- General configuration ------------------------------------------------
needs_sphinx = "1.3"
# Sphinx extension module names and templates location
sys.path.append(os.path.abspath("_extensions"))
extensions = [
"sphinx_tabs.tabs",
"notfound.extension",
"sphinxext.opengraph",
"sphinx_copybutton",
"sphinxcontrib.video",
]
# Warning when the Sphinx Tabs extension is used with unknown
# builders (like the dummy builder) - as it doesn't cause errors,
# we can ignore this so we still can treat other warnings as errors.
sphinx_tabs_nowarn = True
# Disable collapsing tabs for codeblocks.
sphinx_tabs_disable_tab_closing = True
# 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>
""",
}
# 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"
# Don't add `/en/latest` prefix during local development.
# This makes it easier to test the custom 404 page by loading `/404.html`
# on a local web server.
if not on_rtd:
notfound_urls_prefix = ''
# Specify the site name for the Open Graph extension.
ogp_site_name = "Godot Engine documentation"
if not os.getenv("SPHINX_NO_GDSCRIPT"):
extensions.append("gdscript")
if not os.getenv("SPHINX_NO_DESCRIPTIONS"):
extensions.append("godot_descriptions")
templates_path = ["_templates"]
# You can specify multiple suffix as a list of string: ['.rst', '.md']
source_suffix = ".rst"
source_encoding = "utf-8-sig"
# The master toctree document
master_doc = "index"
# General information about the project
project = "Godot Engine"
copyright = (
"2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)"
)
author = "Juan Linietsky, Ariel Manzur and the Godot community"
# Version info for the project, acts as replacement for |version| and |release|
# The short X.Y version
version = os.getenv("READTHEDOCS_VERSION", "latest")
# The full version, including alpha/beta/rc tags
release = version
# 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: F821
# Language / i18n
supported_languages = {
"en": "Godot Engine %s documentation in English",
"de": "Godot Engine %s Dokumentation auf Deutsch",
"es": "Documentación de Godot Engine %s en español",
"fr": "Documentation de Godot Engine %s en français",
"fi": "Godot Engine %s dokumentaatio suomeksi",
"it": "Godot Engine %s documentazione in italiano",
"ja": "Godot Engine %sの日本語のドキュメント",
"ko": "Godot Engine %s 문서 (한국어)",
"pl": "Dokumentacja Godot Engine %s w języku polskim",
"pt_BR": "Documentação da Godot Engine %s em Português Brasileiro",
"ru": "Документация Godot Engine %s на русском языке",
"uk": "Документація до Godot Engine %s українською мовою",
"zh_CN": "Godot Engine %s 简体中文文档",
"zh_TW": "Godot Engine %s 正體中文 (台灣) 文件",
}
# RTD normalized their language codes to ll-cc (e.g. zh-cn),
# but Sphinx did not and still uses ll_CC (e.g. zh_CN).
# `language` is the Sphinx configuration so it needs to be converted back.
language = os.getenv("READTHEDOCS_LANGUAGE", "en")
if "-" in language:
(lang_name, lang_country) = language.split("-")
language = lang_name + "_" + lang_country.upper()
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
print("Build language: {}, i18n tag: {}".format(language, is_i18n))
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 ----------------------------------------------
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
if on_rtd:
using_rtd_theme = True
# Theme options
html_theme_options = {
# if we have a html_logo below, this shows /only/ the logo with no title text
"logo_only": True,
# Collapse navigation (False makes it tree-like)
"collapse_navigation": False,
# Hide the documentation version name/number under the logo
"display_version": False,
}
html_title = supported_languages[language] % ( "(" + version + ")" )
# VCS options: https://docs.readthedocs.io/en/latest/vcs.html#github
html_context = {
"display_github": not is_i18n, # Integrate GitHub
"github_user": "godotengine", # Username
"github_repo": "godot-docs", # Repo name
"github_version": "master", # Version
"conf_py_path": "/", # Path in the checkout to the docs root
"godot_inject_language_links": True,
"godot_docs_supported_languages": list(supported_languages.keys()),
"godot_docs_title": supported_languages[language],
"godot_docs_basepath": "https://docs.godotengine.org/",
"godot_docs_suffix": ".html",
"godot_default_lang": "en",
"godot_canonical_version": "stable",
# Distinguish local development website from production website.
# This prevents people from looking for changes on the production website after making local changes :)
"godot_title_prefix": "" if on_rtd else "(DEV) ",
# Set this to `True` when in the `latest` branch to clearly indicate to the reader
# that they are not reading the `stable` documentation.
"godot_is_latest": True,
"godot_version": "4.4",
# Enables a banner that displays the up-to-date status of each article.
"godot_show_article_status": True,
# Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top.
"godot_show_article_comments": on_rtd and not is_i18n,
}
html_logo = "img/docs_logo.svg"
# These folders are copied to the documentation's HTML output
html_static_path = ["_static"]
html_extra_path = ["robots.txt"]
# These paths are either relative to html_static_path
# or fully qualified paths (e.g. https://...)
html_css_files = [
'css/algolia.css',
'https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css',
"css/custom.css?10", # Increment the number at the end when the file changes to bust the cache.
]
if not on_rtd:
html_css_files.append("css/dev.css")
html_js_files = [
"js/custom.js?7", # Increment the number at the end when the file changes to bust the cache.
]
# Output file base name for HTML help builder
htmlhelp_basename = "GodotEnginedoc"
# -- Options for reStructuredText parser ----------------------------------
# Enable directives that insert the contents of external files
file_insertion_enabled = False
# -- Options for LaTeX output ---------------------------------------------
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(
master_doc,
"GodotEngine.tex",
"Godot Engine Documentation",
"Juan Linietsky, Ariel Manzur and the Godot community",
"manual",
),
]
# -- Options for linkcheck builder ----------------------------------------
# disable checking urls with about.html#this_part_of_page anchors
linkcheck_anchors = False
linkcheck_timeout = 10
# -- I18n settings --------------------------------------------------------
# Godot localization is handled via https://github.com/godotengine/godot-docs-l10n
# where the main docs repo is a submodule. Therefore the translated material is
# actually in the parent folder of this conf.py, hence the "../".
locale_dirs = ["../sphinx/po/"]
gettext_compact = False
# We want to host the localized images in godot-docs-l10n, but Sphinx does not provide
# the necessary feature to do so. `figure_language_filename` has `{root}` and `{path}`,
# but they resolve to (host) absolute paths, so we can't use them as is to access "../".
# However, Python is glorious and lets us redefine Sphinx's internal method that handles
# `figure_language_filename`, so we do our own post-processing to fix the absolute path
# and point to the parallel folder structure in godot-docs-l10n.
# Note: Sphinx's handling of `figure_language_filename` may change in the future, monitor
# https://github.com/sphinx-doc/sphinx/issues/7768 to see what would be relevant for us.
figure_language_filename = "{root}.{language}{ext}"
cwd = os.getcwd()
sphinx_original_get_image_filename_for_language = sphinx.util.i18n.get_image_filename_for_language
def godot_get_image_filename_for_language(filename, env):
"""
Hack the absolute path returned by Sphinx based on `figure_language_filename`
to insert our `../images` relative path to godot-docs-l10n's images folder,
which mirrors the folder structure of the docs repository.
The returned string should also be absolute so that `os.path.exists` can properly
resolve it when trying to concatenate with the original doc folder.
"""
path = sphinx_original_get_image_filename_for_language(filename, env)
path = os.path.abspath(os.path.join("../images/", os.path.relpath(path, cwd)))
return path
sphinx.util.i18n.get_image_filename_for_language = godot_get_image_filename_for_language
# Similar story for the localized class reference, it's out of tree and there doesn't
# seem to be an easy way for us to tweak the toctree to take this into account.
# So we're deleting the existing class reference and adding a symlink instead...
if is_i18n and os.path.exists("../classes/" + language):
import shutil
if os.path.islink("classes"): # Previously made symlink.
os.unlink("classes")
else:
shutil.rmtree("classes")
os.symlink("../classes/" + language, "classes")
# Couldn't find a way to retrieve variables nor do advanced string
# concat from reST, so had to hardcode this in the "epilog" added to
# all pages. This is used in index.rst to display the Weblate badge.
# On English pages, the badge points to the language-neutral engage page.
rst_epilog = """
.. |weblate_widget| image:: https://hosted.weblate.org/widgets/godot-engine/{image_locale}/godot-docs/287x66-white.png
:alt: Translation status
:target: https://hosted.weblate.org/engage/godot-engine{target_locale}/?utm_source=widget
:width: 287
:height: 66
""".format(
image_locale="-" if language == "en" else language,
target_locale="" if language == "en" else "/" + language,
)
# Needed so the table of contents is created for EPUB
epub_tocscope = 'includehidden'