godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity

Port layout changes from the master version

Browse Source 
This also updates the index page, changes the first
sidebar section to be "About" without an extra level,
and renames "Tutorials" to "Manual"

(cherry picked from commit 0c100d9f14)
This commit is contained in:
Yuri Sizov
2023-04-11 10:50:54 +02:00
parent 31df810eaa
commit c03229cd9d
23 changed files with 1390 additions and 568 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.gitignore vendored
View File

@@ -1,3 +1,7 @@
*.csv
!redirects.csv
.env
_build/
env/
__pycache__
@@ -40,3 +44,6 @@ logo.h
# Output of list-unused-images.sh tool
tmp-unused-images
tmp-unused-images-history
# User created Python virtual environement as described in the docs
godot-docs-venv/

212
Makefile
View File

@@ -1,199 +1,37 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
LATEXDEPS = latex dvipng
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SPHINXSOURCEDIR ?= .
SPHINXBUILDDIR ?= _build
SPHINXPAPER ?=
FILELIST ?=
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
ifneq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 0)
define ERROR_MESSAGE
The '$(SPHINXBUILD)' command was not found!
Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to the full path of the '$(SPHINXBUILD)' executable.
Alternatively you can add the executable's directory to your PATH.
If you don't have Sphinx installed, grab it from http://sphinx-doc.org/
endef
$(error ${ERROR_MESSAGE})
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -t i18n .
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
COMMONSPHINXOPTS = $(PAPEROPT_$(SPHINXPAPER)) $(SPHINXOPTS) '$(SPHINXSOURCEDIR)'
DEFAULTSPHINXOPTS = -d $(SPHINXBUILDDIR)/doctrees $(COMMONSPHINXOPTS)
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
.PHONY: help clean
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
@echo " dummy to run only the parse steps without generating output"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GodotEngine.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GodotEngine.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/GodotEngine"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GodotEngine"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@$(SPHINXBUILD) -M help $(DEFAULTSPHINXOPTS) $(O) "$(SPHINXBUILDDIR)"
# This is used by https://github.com/godotengine/godot-docs-l10n
# See https://github.com/godotengine/godot-docs-l10n/blob/f157c0cacc8a6e542e06e96b983b27de91637f8b/update.sh#L92
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) ../sphinx/templates
@echo
@echo "Build finished. The message catalogs are in ../sphinx/templates."
$(SPHINXBUILD) -b gettext -t i18n $(COMMONSPHINXOPTS) ../sphinx/templates $(FILELIST)
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
dummy:
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. No output."
%:
$(SPHINXBUILD) -M $@ $(DEFAULTSPHINXOPTS) $(O) "$(SPHINXBUILDDIR)"/$@ $(FILELIST)

844
_static/css/custom.css
View File

File diff suppressed because it is too large Load Diff

8
_static/css/dev.css Normal file
View File

@@ -0,0 +1,8 @@
/**
* CSS tweaks that are only added outside ReadTheDocs (i.e. when built locally).
*/
/* Re-add default red boxes around Pygments errors */
.highlight .err {
border: 1px solid #FF0000;
}

BIN
_static/css/fonts/JetBrainsMono-Bold.woff2 Normal file
View File

Binary file not shown.

BIN
_static/css/fonts/JetBrainsMono-Medium.woff2 Normal file
View File

Binary file not shown.

BIN
_static/css/fonts/JetBrainsMono-Regular.woff2 Normal file
View File

Binary file not shown.

532
_static/js/custom.js
View File

@@ -1,3 +1,4 @@
// Handle page scroll and adjust sidebar accordingly.
// Each page has two scrolls: the main scroll, which is moving the content of the page;
@@ -7,207 +8,398 @@
// available to the navigation on the fly. There is also a banner below the navigation
// that must be dealt with simultaneously.
const registerOnScrollEvent = (function(){
// Configuration.
// Configuration.
// The number of pixels the user must scroll by before the logo is completely hidden.
const scrollTopPixels = 234;
// The target margin to be applied to the navigation bar when the logo is hidden.
const menuTopMargin = 90;
// The max-height offset when the logo is completely visible.
const menuHeightOffset_default = 338;
// The max-height offset when the logo is completely hidden.
const menuHeightOffset_fixed = 102;
// The distance between the two max-height offset values above; used for intermediate values.
const menuHeightOffset_diff = (menuHeightOffset_default - menuHeightOffset_fixed);
// The number of pixels the user must scroll by before the logo is completely hidden.
const scrollTopPixels = 84;
// The target margin to be applied to the navigation bar when the logo is hidden.
const menuTopMargin = 70;
// The max-height offset when the logo is completely visible.
const menuHeightOffset_default = 162;
// The max-height offset when the logo is completely hidden.
const menuHeightOffset_fixed = 80;
// The distance between the two max-height offset values above; used for intermediate values.
const menuHeightOffset_diff = (menuHeightOffset_default - menuHeightOffset_fixed);
// Media query handler.
return function(mediaQuery) {
// We only apply this logic to the "desktop" resolution (defined by a media query at the bottom).
// This handler is executed when the result of the query evaluation changes, which means that
// the page has moved between "desktop" and "mobile" states.
// Media query handler.
return function(mediaQuery) {
// We only apply this logic to the "desktop" resolution (defined by a media query at the bottom).
// This handler is executed when the result of the query evaluation changes, which means that
// the page has moved between "desktop" and "mobile" states.
// When entering the "desktop" state, we register scroll events and adjust elements on the page.
// When entering the "mobile" state, we clean up any registered events and restore elements on the page
// to their initial state.
// When entering the "desktop" state, we register scroll events and adjust elements on the page.
// When entering the "mobile" state, we clean up any registered events and restore elements on the page
// to their initial state.
const $window = $(window);
const $sidebar = $('.wy-side-scroll');
const $search = $sidebar.children('.wy-side-nav-search');
const $menu = $sidebar.children('.wy-menu-vertical');
const $ethical = $sidebar.children('.ethical-rtd');
const $window = $(window);
const $sidebar = $('.wy-side-scroll');
const $search = $sidebar.children('.wy-side-nav-search');
const $menu = $sidebar.children('.wy-menu-vertical');
const $ethical = $sidebar.children('.ethical-rtd');
// This padding is needed to correctly adjust the height of the scrollable area in the sidebar.
// It has to have the same height as the ethical block, if there is one.
let $menuPadding = $menu.children('.wy-menu-ethical-padding');
if ($menuPadding.length == 0) {
$menuPadding = $('<div class="wy-menu-ethical-padding"></div>');
$menu.append($menuPadding);
}
if (mediaQuery.matches) {
// Entering the "desktop" state.
// The main scroll event handler.
// Executed as the page is scrolled and once immediatelly as the page enters this state.
const handleMainScroll = (currentScroll) => {
if (currentScroll >= scrollTopPixels) {
// After the page is scrolled below the threshold, we fix everything in place.
$search.css('margin-top', `-${scrollTopPixels}px`);
$menu.css('margin-top', `${menuTopMargin}px`);
$menu.css('max-height', `calc(100% - ${menuHeightOffset_fixed}px)`);
}
else {
// Between the top of the page and the threshold we calculate intermediate values
// to guarantee a smooth transition.
$search.css('margin-top', `-${currentScroll}px`);
$menu.css('margin-top', `${menuTopMargin + (scrollTopPixels - currentScroll)}px`);
if (currentScroll > 0) {
const scrolledPercent = (scrollTopPixels - currentScroll) / scrollTopPixels;
const offsetValue = menuHeightOffset_fixed + menuHeightOffset_diff * scrolledPercent;
$menu.css('max-height', `calc(100% - ${offsetValue}px)`);
} else {
$menu.css('max-height', `calc(100% - ${menuHeightOffset_default}px)`);
}
}
};
// The sidebar scroll event handler.
// Executed as the sidebar is scrolled as well as after the main scroll. This is needed
// because the main scroll can affect the scrollable area of the sidebar.
const handleSidebarScroll = () => {
const menuElement = $menu.get(0);
const menuScrollTop = $menu.scrollTop();
const menuScrollBottom = menuElement.scrollHeight - (menuScrollTop + menuElement.offsetHeight);
// As the navigation is scrolled we add a shadow to the top bar hanging over it.
if (menuScrollTop > 0) {
$search.addClass('fixed-and-scrolled');
} else {
$search.removeClass('fixed-and-scrolled');
}
// Near the bottom we start moving the sidebar banner into view.
if (menuScrollBottom < ethicalOffsetBottom) {
$ethical.css('display', 'block');
$ethical.css('margin-top', `-${ethicalOffsetBottom - menuScrollBottom}px`);
} else {
$ethical.css('display', 'none');
$ethical.css('margin-top', '0px');
}
};
$search.addClass('fixed');
$ethical.addClass('fixed');
// Adjust the inner height of navigation so that the banner can be overlaid there later.
const ethicalOffsetBottom = $ethical.height() || 0;
if (ethicalOffsetBottom) {
$menuPadding.css('height', `${ethicalOffsetBottom}px`);
} else {
$menuPadding.css('height', `0px`);
// This padding is needed to correctly adjust the height of the scrollable area in the sidebar.
// It has to have the same height as the ethical block, if there is one.
let $menuPadding = $menu.children('.wy-menu-ethical-padding');
if ($menuPadding.length == 0) {
$menuPadding = $('<div class="wy-menu-ethical-padding"></div>');
$menu.append($menuPadding);
}
$window.scroll(function() {
if (mediaQuery.matches) {
// Entering the "desktop" state.
// The main scroll event handler.
// Executed as the page is scrolled and once immediately as the page enters this state.
const handleMainScroll = (currentScroll) => {
if (currentScroll >= scrollTopPixels) {
// After the page is scrolled below the threshold, we fix everything in place.
$search.css('margin-top', `-${scrollTopPixels}px`);
$menu.css('margin-top', `${menuTopMargin}px`);
$menu.css('max-height', `calc(100% - ${menuHeightOffset_fixed}px)`);
}
else {
// Between the top of the page and the threshold we calculate intermediate values
// to guarantee a smooth transition.
$search.css('margin-top', `-${currentScroll}px`);
$menu.css('margin-top', `${menuTopMargin + (scrollTopPixels - currentScroll)}px`);
if (currentScroll > 0) {
const scrolledPercent = (scrollTopPixels - currentScroll) / scrollTopPixels;
const offsetValue = menuHeightOffset_fixed + menuHeightOffset_diff * scrolledPercent;
$menu.css('max-height', `calc(100% - ${offsetValue}px)`);
} else {
$menu.css('max-height', `calc(100% - ${menuHeightOffset_default}px)`);
}
}
};
// The sidebar scroll event handler.
// Executed as the sidebar is scrolled as well as after the main scroll. This is needed
// because the main scroll can affect the scrollable area of the sidebar.
const handleSidebarScroll = () => {
const menuElement = $menu.get(0);
const menuScrollTop = $menu.scrollTop();
const menuScrollBottom = menuElement.scrollHeight - (menuScrollTop + menuElement.offsetHeight);
// As the navigation is scrolled we add a shadow to the top bar hanging over it.
if (menuScrollTop > 0) {
$search.addClass('fixed-and-scrolled');
} else {
$search.removeClass('fixed-and-scrolled');
}
// Near the bottom we start moving the sidebar banner into view.
if (menuScrollBottom < ethicalOffsetBottom) {
$ethical.css('display', 'block');
$ethical.css('margin-top', `-${ethicalOffsetBottom - menuScrollBottom}px`);
} else {
$ethical.css('display', 'none');
$ethical.css('margin-top', '0px');
}
};
$search.addClass('fixed');
$ethical.addClass('fixed');
// Adjust the inner height of navigation so that the banner can be overlaid there later.
const ethicalOffsetBottom = $ethical.height() || 0;
if (ethicalOffsetBottom) {
$menuPadding.css('height', `${ethicalOffsetBottom}px`);
} else {
$menuPadding.css('height', `0px`);
}
$window.scroll(function() {
handleMainScroll(window.scrollY);
handleSidebarScroll();
});
$menu.scroll(function() {
handleSidebarScroll();
});
handleMainScroll(window.scrollY);
handleSidebarScroll();
});
} else {
// Entering the "mobile" state.
$menu.scroll(function() {
handleSidebarScroll();
});
$window.unbind('scroll');
$menu.unbind('scroll');
handleMainScroll(window.scrollY);
handleSidebarScroll();
} else {
// Entering the "mobile" state.
$search.removeClass('fixed');
$ethical.removeClass('fixed');
$window.unbind('scroll');
$menu.unbind('scroll');
$search.removeClass('fixed');
$ethical.removeClass('fixed');
$search.css('margin-top', `0px`);
$menu.css('margin-top', `0px`);
$menu.css('max-height', 'initial');
$menuPadding.css('height', `0px`);
$ethical.css('margin-top', '0px');
$ethical.css('display', 'block');
}
};
})();
// Subscribe to DOM changes in the sidebar container, because there is a
// banner that gets added at a later point, that we might not catch otherwise.
const registerSidebarObserver = (function(){
return function(callback) {
const sidebarContainer = document.querySelector('.wy-side-scroll');
let sidebarEthical = null;
const registerEthicalObserver = () => {
if (sidebarEthical) {
// Do it only once.
return;
$search.css('margin-top', `0px`);
$menu.css('margin-top', `0px`);
$menu.css('max-height', 'initial');
$menuPadding.css('height', `0px`);
$ethical.css('margin-top', '0px');
$ethical.css('display', 'block');
}
};
})();
sidebarEthical = sidebarContainer.querySelector('.ethical-rtd');
if (!sidebarEthical) {
// Do it only after we have the element there.
return;
}
// Subscribe to DOM changes in the sidebar container, because there is a
// banner that gets added at a later point, that we might not catch otherwise.
const registerSidebarObserver = (function(){
return function(callback) {
const sidebarContainer = document.querySelector('.wy-side-scroll');
// This observer watches over the ethical block in sidebar, and all of its subtree.
const ethicalObserverConfig = { childList: true, subtree: true };
const ethicalObserverCallback = (mutationsList, observer) => {
let sidebarEthical = null;
const registerEthicalObserver = () => {
if (sidebarEthical) {
// Do it only once.
return;
}
sidebarEthical = sidebarContainer.querySelector('.ethical-rtd');
if (!sidebarEthical) {
// Do it only after we have the element there.
return;
}
// This observer watches over the ethical block in sidebar, and all of its subtree.
const ethicalObserverConfig = { childList: true, subtree: true };
const ethicalObserverCallback = (mutationsList, observer) => {
for (let mutation of mutationsList) {
if (mutation.type !== 'childList') {
continue;
}
callback();
}
};
const ethicalObserver = new MutationObserver(ethicalObserverCallback);
ethicalObserver.observe(sidebarEthical, ethicalObserverConfig);
};
registerEthicalObserver();
// This observer watches over direct children of the main sidebar container.
const observerConfig = { childList: true };
const observerCallback = (mutationsList, observer) => {
for (let mutation of mutationsList) {
if (mutation.type !== 'childList') {
continue;
}
callback();
registerEthicalObserver();
}
};
const ethicalObserver = new MutationObserver(ethicalObserverCallback);
ethicalObserver.observe(sidebarEthical, ethicalObserverConfig);
};
registerEthicalObserver();
const observer = new MutationObserver(observerCallback);
observer.observe(sidebarContainer, observerConfig);
// This observer watches over direct children of the main sidebar container.
const observerConfig = { childList: true };
const observerCallback = (mutationsList, observer) => {
for (let mutation of mutationsList) {
if (mutation.type !== 'childList') {
continue;
// Default TOC tree has links that immediately navigate to the selected page. Our
// theme adds an extra button to fold and unfold the tree without navigating away.
// But that means that the buttons are added after the initial load, so we need to
// improvise to detect clicks on these buttons.
const scrollElement = document.querySelector('.wy-menu-vertical');
const registerLinkHandler = (linkChildren) => {
linkChildren.forEach(it => {
if (it.nodeType === Node.ELEMENT_NODE && it.classList.contains('toctree-expand')) {
it.addEventListener('click', () => {
// Toggling a different item will close the currently opened one,
// which may shift the clicked item out of the view. We correct for that.
const menuItem = it.parentNode;
const baseScrollOffset = scrollElement.scrollTop + scrollElement.offsetTop;
const maxScrollOffset = baseScrollOffset + scrollElement.offsetHeight;
if (menuItem.offsetTop < baseScrollOffset || menuItem.offsetTop > maxScrollOffset) {
menuItem.scrollIntoView();
}
callback();
});
}
});
}
const navigationSections = document.querySelectorAll('.wy-menu-vertical ul');
navigationSections.forEach(it => {
if (it.previousSibling == null || typeof it.previousSibling === 'undefined' || it.previousSibling.tagName != 'A') {
return;
}
callback();
registerEthicalObserver();
}
const navigationLink = it.previousSibling;
registerLinkHandler(navigationLink.childNodes);
const linkObserverConfig = { childList: true };
const linkObserverCallback = (mutationsList, observer) => {
for (let mutation of mutationsList) {
registerLinkHandler(mutation.addedNodes);
}
};
const linkObserver = new MutationObserver(linkObserverCallback);
linkObserver.observe(navigationLink, linkObserverConfig);
});
};
})();
const observer = new MutationObserver(observerCallback);
observer.observe(sidebarContainer, observerConfig);
};
})();
$(document).ready(() => {
// Remove the search match highlights from the page, and adjust the URL in the
// navigation history.
const url = new URL(location.href);
if (url.searchParams.has('highlight')) {
Documentation.hideSearchWords();
}
$(document).ready(() => {
const mediaQuery = window.matchMedia('only screen and (min-width: 769px)');
// Initialize handlers for page scrolling and our custom sidebar.
const mediaQuery = window.matchMedia('only screen and (min-width: 769px)');
registerOnScrollEvent(mediaQuery);
mediaQuery.addListener(registerOnScrollEvent);
registerSidebarObserver(() => {
registerOnScrollEvent(mediaQuery);
mediaQuery.addListener(registerOnScrollEvent);
registerSidebarObserver(() => {
registerOnScrollEvent(mediaQuery);
});
// Add line-break suggestions to the sidebar navigation items in the class reference section.
//
// Some class reference pages have very long PascalCase names, such as
// VisualShaderNodeCurveXYZTexture
// Those create issues for our layout, as we can neither make them wrap with CSS without
// breaking normal article titles, nor is it good to have them overflow their containers.
// So we use a <wbr> tag to insert mid-word suggestions for appropriate splits, so the browser
// knows that it's okay to split it like
// Visual Shader Node Curve XYZTexture
// and add a new line at an opportune moment.
const classReferenceLinks = document.querySelectorAll('.wy-menu-vertical > ul:last-of-type .reference.internal');
for (const linkItem of classReferenceLinks) {
let textNode = null;
linkItem.childNodes.forEach(it => {
if (it.nodeType === Node.TEXT_NODE) {
// If this is a text node and if it needs to be updated, store a reference.
let text = it.textContent;
if (!(text.includes(" ") || text.length < 10)) {
textNode = it;
}
}
});
if (textNode != null) {
let text = textNode.textContent;
// Add suggested line-breaks and replace the original text.
// The regex looks for a lowercase letter followed by a number or an uppercase
// letter. We avoid splitting at the last character in the name, though.
text = text.replace(/([a-z])([A-Z0-9](?!$))/gm, '$1<wbr>$2');
linkItem.removeChild(textNode);
linkItem.insertAdjacentHTML('beforeend', text);
}
}
// See `godot_is_latest` in conf.py
const isLatest = document.querySelector('meta[name=doc_is_latest]').content.toLowerCase() === 'true';
if (isLatest) {
// Add a compatibility notice using JavaScript so it doesn't end up in the
// automatically generated `meta description` tag.
const baseUrl = [location.protocol, '//', location.host, location.pathname].join('');
// These lines only work as expected in the production environment, can't test this locally.
const fallbackUrl = baseUrl.replace('/latest/', '/stable/');
const homeUrl = baseUrl.split('/latest/')[0] + '/stable/';
const searchUrl = homeUrl + 'search.html?q=';
const noticeLink = document.querySelector('.latest-notice-link');
// Insert a placeholder to display as we're making a request.
noticeLink.innerHTML = `
Checking the <a class="reference" href="${homeUrl}">stable version</a>
of the documentation...
`;
// Make a HEAD request to the possible stable URL to check if the page exists.
fetch(fallbackUrl, { method: 'HEAD' })
.then((res) => {
// We only check the HTTP status, which should tell us if the link is valid or not.
if (res.status === 200) {
noticeLink.innerHTML = `
See the <a class="reference" href="${fallbackUrl}">stable version</a>
of this documentation page instead.
`;
} else {
// Err, just to fallthrough to catch.
throw Error('Bad request');
}
})
.catch((err) => {
let message = `
This page does not exist in the <a class="reference" href="${homeUrl}">stable version</a>
of the documentation.
`;
// Also suggest a search query using the page's title. It should work with translations as well.
// Note that we can't use the title tag as it has a permanent suffix. OG title doesn't, though.
const titleMeta = document.querySelector('meta[property="og:title"]');
if (typeof titleMeta !== 'undefined') {
const pageTitle = titleMeta.getAttribute('content');
message += `
You can try searching for "<a class="reference" href="${searchUrl + encodeURIComponent(pageTitle)}">${pageTitle}</a>" instead.
`;
}
noticeLink.innerHTML = message;
});
}
// Load instant.page to prefetch pages upon hovering. This makes navigation feel
// snappier. The script is dynamically appended as Read the Docs doesn't have
// a way to add scripts with a "module" attribute.
const instantPageScript = document.createElement('script');
instantPageScript.toggleAttribute('module');
/*! instant.page v5.1.0 - (C) 2019-2020 Alexandre Dieulot - https://instant.page/license */
instantPageScript.innerText = 'let t,e;const n=new Set,o=document.createElement("link"),i=o.relList&&o.relList.supports&&o.relList.supports("prefetch")&&window.IntersectionObserver&&"isIntersecting"in IntersectionObserverEntry.prototype,s="instantAllowQueryString"in document.body.dataset,a="instantAllowExternalLinks"in document.body.dataset,r="instantWhitelist"in document.body.dataset,c="instantMousedownShortcut"in document.body.dataset,d=1111;let l=65,u=!1,f=!1,m=!1;if("instantIntensity"in document.body.dataset){const t=document.body.dataset.instantIntensity;if("mousedown"==t.substr(0,"mousedown".length))u=!0,"mousedown-only"==t&&(f=!0);else if("viewport"==t.substr(0,"viewport".length))navigator.connection&&(navigator.connection.saveData||navigator.connection.effectiveType&&navigator.connection.effectiveType.includes("2g"))||("viewport"==t?document.documentElement.clientWidth*document.documentElement.clientHeight<45e4&&(m=!0):"viewport-all"==t&&(m=!0));else{const e=parseInt(t);isNaN(e)||(l=e)}}if(i){const n={capture:!0,passive:!0};if(f||document.addEventListener("touchstart",function(t){e=performance.now();const n=t.target.closest("a");if(!h(n))return;v(n.href)},n),u?c||document.addEventListener("mousedown",function(t){const e=t.target.closest("a");if(!h(e))return;v(e.href)},n):document.addEventListener("mouseover",function(n){if(performance.now()-e<d)return;const o=n.target.closest("a");if(!h(o))return;o.addEventListener("mouseout",p,{passive:!0}),t=setTimeout(()=>{v(o.href),t=void 0},l)},n),c&&document.addEventListener("mousedown",function(t){if(performance.now()-e<d)return;const n=t.target.closest("a");if(t.which>1||t.metaKey||t.ctrlKey)return;if(!n)return;n.addEventListener("click",function(t){1337!=t.detail&&t.preventDefault()},{capture:!0,passive:!1,once:!0});const o=new MouseEvent("click",{view:window,bubbles:!0,cancelable:!1,detail:1337});n.dispatchEvent(o)},n),m){let t;(t=window.requestIdleCallback?t=>{requestIdleCallback(t,{timeout:1500})}:t=>{t()})(()=>{const t=new IntersectionObserver(e=>{e.forEach(e=>{if(e.isIntersecting){const n=e.target;t.unobserve(n),v(n.href)}})});document.querySelectorAll("a").forEach(e=>{h(e)&&t.observe(e)})})}}function p(e){e.relatedTarget&&e.target.closest("a")==e.relatedTarget.closest("a")||t&&(clearTimeout(t),t=void 0)}function h(t){if(t&&t.href&&(!r||"instant"in t.dataset)&&(a||t.origin==location.origin||"instant"in t.dataset)&&["http:","https:"].includes(t.protocol)&&("http:"!=t.protocol||"https:"!=location.protocol)&&(s||!t.search||"instant"in t.dataset)&&!(t.hash&&t.pathname+t.search==location.pathname+location.search||"noInstant"in t.dataset))return!0}function v(t){if(n.has(t))return;const e=document.createElement("link");e.rel="prefetch",e.href=t,document.head.appendChild(e),n.add(t)}';
document.head.appendChild(instantPageScript);
// Make sections in the sidebar togglable.
let hasCurrent = false;
let menuHeaders = document.querySelectorAll('.wy-menu-vertical .caption[role=heading]');
menuHeaders.forEach(it => {
let connectedMenu = it.nextElementSibling;
// Enable toggling.
it.addEventListener('click', () => {
if (connectedMenu.classList.contains('active')) {
connectedMenu.classList.remove('active');
it.classList.remove('active');
} else {
connectedMenu.classList.add('active');
it.classList.add('active');
}
// Hide other sections.
menuHeaders.forEach(ot => {
if (ot !== it && ot.classList.contains('active')) {
ot.nextElementSibling.classList.remove('active');
ot.classList.remove('active');
}
});
registerOnScrollEvent(mediaQuery);
}, true);
// Set the default state, expand our current section.
if (connectedMenu.classList.contains('current')) {
connectedMenu.classList.add('active');
it.classList.add('active');
hasCurrent = true;
}
});
// Unfold the first (general information) section on the home page.
if (!hasCurrent && menuHeaders.length > 0) {
menuHeaders[0].classList.add('active');
menuHeaders[0].nextElementSibling.classList.add('active');
registerOnScrollEvent(mediaQuery);
}
});
// Load instant.page to prefetch pages upon hovering. This makes navigation feel
// snappier. The script is dynamically appended as Read the Docs doesn't have
// a way to add scripts with a "module" attribute.
const instantPageScript = document.createElement('script');
instantPageScript.toggleAttribute('module');
/*! instant.page v5.1.0 - (C) 2019-2020 Alexandre Dieulot - https://instant.page/license */
instantPageScript.innerText = 'let t,e;const n=new Set,o=document.createElement("link"),i=o.relList&&o.relList.supports&&o.relList.supports("prefetch")&&window.IntersectionObserver&&"isIntersecting"in IntersectionObserverEntry.prototype,s="instantAllowQueryString"in document.body.dataset,a="instantAllowExternalLinks"in document.body.dataset,r="instantWhitelist"in document.body.dataset,c="instantMousedownShortcut"in document.body.dataset,d=1111;let l=65,u=!1,f=!1,m=!1;if("instantIntensity"in document.body.dataset){const t=document.body.dataset.instantIntensity;if("mousedown"==t.substr(0,"mousedown".length))u=!0,"mousedown-only"==t&&(f=!0);else if("viewport"==t.substr(0,"viewport".length))navigator.connection&&(navigator.connection.saveData||navigator.connection.effectiveType&&navigator.connection.effectiveType.includes("2g"))||("viewport"==t?document.documentElement.clientWidth*document.documentElement.clientHeight<45e4&&(m=!0):"viewport-all"==t&&(m=!0));else{const e=parseInt(t);isNaN(e)||(l=e)}}if(i){const n={capture:!0,passive:!0};if(f||document.addEventListener("touchstart",function(t){e=performance.now();const n=t.target.closest("a");if(!h(n))return;v(n.href)},n),u?c||document.addEventListener("mousedown",function(t){const e=t.target.closest("a");if(!h(e))return;v(e.href)},n):document.addEventListener("mouseover",function(n){if(performance.now()-e<d)return;const o=n.target.closest("a");if(!h(o))return;o.addEventListener("mouseout",p,{passive:!0}),t=setTimeout(()=>{v(o.href),t=void 0},l)},n),c&&document.addEventListener("mousedown",function(t){if(performance.now()-e<d)return;const n=t.target.closest("a");if(t.which>1||t.metaKey||t.ctrlKey)return;if(!n)return;n.addEventListener("click",function(t){1337!=t.detail&&t.preventDefault()},{capture:!0,passive:!1,once:!0});const o=new MouseEvent("click",{view:window,bubbles:!0,cancelable:!1,detail:1337});n.dispatchEvent(o)},n),m){let t;(t=window.requestIdleCallback?t=>{requestIdleCallback(t,{timeout:1500})}:t=>{t()})(()=>{const t=new IntersectionObserver(e=>{e.forEach(e=>{if(e.isIntersecting){const n=e.target;t.unobserve(n),v(n.href)}})});document.querySelectorAll("a").forEach(e=>{h(e)&&t.observe(e)})})}}function p(e){e.relatedTarget&&e.target.closest("a")==e.relatedTarget.closest("a")||t&&(clearTimeout(t),t=void 0)}function h(t){if(t&&t.href&&(!r||"instant"in t.dataset)&&(a||t.origin==location.origin||"instant"in t.dataset)&&["http:","https:"].includes(t.protocol)&&("http:"!=t.protocol||"https:"!=location.protocol)&&(s||!t.search||"instant"in t.dataset)&&!(t.hash&&t.pathname+t.search==location.pathname+location.search||"noInstant"in t.dataset))return!0}function v(t){if(n.has(t))return;const e=document.createElement("link");e.rel="prefetch",e.href=t,document.head.appendChild(e),n.add(t)}';
document.head.appendChild(instantPageScript);
});
// Override the default implementation from doctools.js to avoid this behavior.
Documentation.highlightSearchWords = function() {
// Nope.
}

46
_templates/breadcrumbs.html
View File

@@ -1,24 +1,40 @@
{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
{% block breadcrumbs %}
<li>
<div style="font-size: 105%;font-weight: 600;">
{{ godot_docs_title | replace("%s", godot_version) }}
</div>
<ul class="wy-breadcrumbs">
{{ super() }}
</ul>
</li>
{% endblock %}
{% block breadcrumbs_aside %}
{% if not meta or meta.get('github_url') != 'hide' %}
{{ super() }}
<li style="float: right; text-align: right;">
<ul>
{{ super() }}
</ul>
<style>
.godot-edit-guidelines {
font-size: 14px;
float: right;
clear: both;
}
@media screen and (max-width: 480px) {
<style>
.godot-edit-guidelines {
display: none;
font-size: 14px;
float: right;
clear: both;
padding-top: 4px;
}
}
</style>
<a class="godot-edit-guidelines" href="https://docs.godotengine.org/en/latest/community/contributing/index.html#writing-documentation">
Learn how to contribute!
</a>
@media screen and (max-width: 480px) {
.godot-edit-guidelines {
display: none;
}
}
</style>
<a class="godot-edit-guidelines" href="https://docs.godotengine.org/en/latest/contributing/documentation/index.html#writing-documentation">
Learn how to contribute!
</a>
</li>
{% endif %}
{% endblock %}

63
_templates/layout.html
View File

@@ -1,4 +1,15 @@
{% extends "!layout.html" -%}
{# Refer to https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html #}
{% block htmltitle -%}
<title>{{ godot_title_prefix }}{{ title|striptags|e }}{{ titlesuffix }}</title>
{% endblock -%}
{% block extrahead -%}
<meta name="doc_version" content="{{ version }}">
<meta name="doc_is_latest" content="{{ godot_is_latest }}">
{% endblock -%}
{% block linktags -%}
<meta name="theme-color" content="#3d8fcc">
{% if godot_inject_language_links -%}
@@ -14,6 +25,52 @@
{{ super() }}
{% endblock -%}
{% block htmltitle -%}
<title>{{ godot_title_prefix }}{{ title|striptags|e }}{{ titlesuffix }}</title>
{% endblock -%}
{%- block document %}
<div itemprop="articleBody">
{% if godot_is_latest or godot_show_article_status %}
<div class="admonition-grid">
{% if godot_is_latest %}
<div class="admonition attention latest-notice">
<p class="first admonition-title">Attention: Here be dragons</p>
<p>
This is the <code class="docutils literal notranslate"><span class="pre">latest</span></code>
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
</p>
<p class="last latest-notice-link">
Checking the stable version of the documentation...
</p>
</div>
{% endif %}
{% if godot_show_article_status and not godot_is_latest %}
<div class="admonition tip article-status">
{% if meta and meta.get('article_outdated') == 'True' %}
<p class="first admonition-title">Work in progress</p>
<p>
The content of this page was not yet updated for Godot
<code class="docutils literal notranslate">{{ godot_version }}</code>
and may be <strong>outdated</strong>. If you know how to improve this page or you can confirm
that it's up to date, feel free to <a href="https://github.com/godotengine/godot-docs">open a pull request</a>.
</p>
{% else %}
<p class="first admonition-title">Up to date</p>
<p>
This page is <strong>up to date</strong> for Godot <code class="docutils literal notranslate">{{ godot_version }}</code>.
If you still find outdated information, please <a href="https://github.com/godotengine/godot-docs">open an issue</a>.
</p>
{% endif %}
</div>
{% endif %}
</div>
{% endif %}
{% block body %}{% endblock %}
</div>
{%- if self.comments()|trim %}
<div class="articleComments">
{%- block comments %}{% endblock %}
</div>
{%- endif%}
</div>
{%- endblock %}

60
_templates/versions.html Normal file
View File

@@ -0,0 +1,60 @@
{# Add rst-badge after rst-versions for small badge style. #}
{% set display_version = version -%}
{% set listed_languages = ({"en":"#", "de":"#", "es":"#", "fr":"#"}).items() -%}
{% set listed_versions = ({"stable":"#", "latest":"#"}).items() -%}
{% if READTHEDOCS and current_version %}
{% set display_version = current_version -%}
{% endif %}
{% if READTHEDOCS and versions %}
{% set listed_versions = versions -%}
{% endif %}
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Read the Docs</span>
v: {{ display_version }}{% if display_version != godot_version %} ({{ godot_version }}){% endif %}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
{#
The contents of this element will be replaced in production.
But we can still have some mock data for testing.
#}
<dl>
<dt>{{ _('Languages') }}</dt>
{% for slug, url in listed_languages %}
<dd><a href="{{ url }}">{{ slug }}</a></dd>
{% endfor %}
</dl>
<dl>
<dt>{{ _('Versions') }}</dt>
{% for slug, url in listed_versions %}
<dd><a href="{{ url }}">{{ slug }}</a></dd>
{% endfor %}
</dl>
<dl>
{# Translators: The phrase "Read the Docs" is not translated #}
<dt>{{ _('On Read the Docs') }}</dt>
<dd>
<a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}">{{ _('Project Home') }}</a>
</dd>
<dd>
<a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/builds/">{{ _('Builds') }}</a>
</dd>
<dd>
<a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/downloads/">{{ _('Downloads') }}</a>
</dd>
</dl>
<hr>
<small>
<span>Hosted by <a href="https://readthedocs.org">Read the Docs</a></span>
<span> · </span>
<a href="https://docs.readthedocs.io/page/privacy-policy.html">Privacy Policy</a>
</small>
{##}
</div>
</div>

2
about/docs_changelog.rst
View File

@@ -5,7 +5,7 @@ Documentation changelog
The documentation is continually being improved. The release of version 3.2
includes many new tutorials, many fixes and updates for old tutorials, and many updates
to the :ref:`class reference <toc-class-ref>`. Below is a list of new tutorials
to the :ref:`class reference <doc_class_reference>`. Below is a list of new tutorials
added since version 3.1.
.. note:: This document only contains new tutorials so not all changes are reflected,

18
about/index.rst
View File

@@ -1,18 +0,0 @@
About
=====
.. toctree::
:maxdepth: 1
:name: toc-about
introduction
faq
troubleshooting
list_of_features
docs_changelog
release_policy
complying_with_licenses
.. history
.. authors
.. license

2
classes/index.rst
View File

@@ -1,5 +1,7 @@
:github_url: hide
.. _doc_class_reference:
Godot API
=========

2
community/contributing/contributing_to_the_documentation.rst
View File

@@ -26,7 +26,7 @@ request triggers a rebuild of the online documentation upon merging.
.. warning:: The class reference's source files are in the `Godot engine
repository <https://github.com/godotengine/godot>`_. We generate
the :ref:`Godot API <toc-class-ref>` section of this documentation
the :ref:`Godot API <doc_class_reference>` section of this documentation
from them. If you want to update the description of a class, its
methods, or properties, read
:ref:`doc_updating_the_class_reference`.

4
community/contributing/documentation_guidelines.rst
View File

@@ -27,8 +27,8 @@ documentation.
.. warning:: The class reference's source files are in the `Godot engine repository
<https://github.com/godotengine/godot>`_. We generate the :ref:`Godot API
<toc-class-ref>` section of this documentation from them. If you want to update the
description of a class, its methods, or properties, read
<doc_class_reference>` section of this documentation from them. If you want
to update the description of a class, its methods, or properties, read
:ref:`doc_updating_the_class_reference`.
.. warning:: If you want to edit the **API reference**, please note that it

4
community/contributing/updating_the_class_reference.rst
View File

@@ -5,7 +5,7 @@ Contributing to the class reference
.. highlight:: shell
The class reference is available online in the :ref:`classes <toc-class-ref>`
The class reference is available online in the :ref:`classes <doc_class_reference>`
section of the documentation and in the Godot editor, from the help menu.
In the class reference, some methods, variables, and signals lack descriptions.
@@ -45,7 +45,7 @@ repository: `doc/classes/
.. warning:: Always edit the API reference through these source XML files. Do
not edit the generated ``.rst`` files :ref:`in the online documentation
<toc-class-ref>`, hosted in the `godot-docs
<doc_class_reference>`, hosted in the `godot-docs
<https://github.com/godotengine/godot-docs>`_ repository.
.. warning::

2
community/contributing/ways_to_contribute.rst
View File

@@ -197,7 +197,7 @@ There are two separate resources referred to as "documentation" in Godot:
- **The class reference.** This is the documentation for the complete Godot API
as exposed to GDScript and the other scripting languages. It can be consulted
offline, directly in Godot's code editor, or online at :ref:`Godot API
<toc-class-ref>`. To contribute to the class reference, you have to edit the
<doc_class_reference>`. To contribute to the class reference, you have to edit the
XML file corresponding to the class and make a pull request.
See :ref:`doc_updating_the_class_reference` and
:ref:`doc_class_reference_writing_guidelines` for more details.

53
conf.py
View File

@@ -2,6 +2,7 @@
#
# Godot Engine documentation build configuration file
import sphinx
import sphinx_rtd_theme
import sys
import os
@@ -76,7 +77,7 @@ 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)"
"2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)"
)
author = "Juan Linietsky, Ariel Manzur and the Godot community"
@@ -96,20 +97,20 @@ if env_tags is not None:
# 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) 正體中文 (台灣) 文件",
"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 正體中文 (台灣) 文件",
}
language = os.getenv("READTHEDOCS_LANGUAGE", "en")
@@ -154,9 +155,11 @@ html_theme_options = {
"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
html_title = supported_languages[language] % ( "(" + version + ")" )
# VCS options: https://docs.readthedocs.io/en/latest/vcs.html#github
html_context = {
@@ -167,6 +170,7 @@ html_context = {
"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",
@@ -174,9 +178,15 @@ html_context = {
# 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": False,
"godot_version": "3.5",
# Enables a banner that displays the up-to-date status of each article.
"godot_show_article_status": False,
}
html_logo = "img/docs_logo.png"
html_logo = "img/docs_logo.svg"
# These folders are copied to the documentation's HTML output
html_static_path = ["_static"]
@@ -186,11 +196,14 @@ 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/custom.css",
"css/custom.css?1", # 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",
"js/custom.js?1", # Increment the number at the end when the file changes to bust the cache.
]
# Output file base name for HTML help builder
@@ -242,11 +255,11 @@ gettext_compact = False
# https://github.com/sphinx-doc/sphinx/issues/7768 to see what would be relevant for us.
figure_language_filename = "{root}.{language}{ext}"
import sphinx
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`

2
getting_started/introduction/learning_new_features.rst
View File

@@ -33,7 +33,7 @@ from within the Godot editor. To do so, go to Help -> Search or press
.. image:: img/manual_class_reference_search.png
To browse it online, head to the manual's :ref:`Class Reference <toc-class-ref>`
To browse it online, head to the manual's :ref:`Class Reference <doc_class_reference>`
section.
A class reference's page tells you:

BIN
img/docs_logo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 38 KiB

1
img/docs_logo.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

96
index.rst
View File

@@ -10,7 +10,7 @@ Godot Docs – *3.5* branch
.. only:: i18n
.. note:: This documentation is translated from the `original English one
<https://docs.godotengine.org/en/latest>`_ by community members
<https://docs.godotengine.org/en/stable>`_ by community members
on `Weblate <https://hosted.weblate.org/projects/godot-engine/godot-docs>`_.
Depending on the translation effort's completion level, you may
@@ -19,8 +19,9 @@ Godot Docs – *3.5* branch
ones on Weblate.
For the time being, localized translations are only available for
the "latest" (development) branch, but should be suitable to learn
how to use stable Godot releases nevertheless.
the "stable" branch. You can still view the English documentation for
other engine versions using the "Read the Docs" panel at the bottom
of the sidebar.
Welcome to the official documentation of `Godot Engine <https://godotengine.org>`__,
the free and open source community-driven 2D and 3D game engine! If you are new
@@ -28,42 +29,62 @@ to this documentation, we recommend that you read the
:ref:`introduction page <doc_about_intro>` to get an overview of what this
documentation has to offer.
The table of contents below and in the sidebar should let you easily access the
documentation for your topic of interest. You can also use the search function
in the top left corner.
The table of contents in the sidebar should let you easily access the documentation
for your topic of interest. You can also use the search function in the top-left corner.
You can also `download an HTML copy <https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-stable.zip>`__
for offline reading (updated every Monday). Extract the ZIP archive then open
the top-level ``index.html`` in a web browser.
Get involved
------------
.. note:: Godot Engine is an open source project developed by a community of
volunteers. The documentation team can always use your
feedback and help to improve the tutorials and class reference. If
you don't understand something, or cannot find what you
are looking for in the docs, help us make the documentation better
by letting us know!
Godot Engine is an open source project developed by a community of volunteers.
The documentation team can always use your feedback and help to improve the
tutorials and class reference. If you don't understand something, or cannot find
what you are looking for in the docs, help us make the documentation better
by letting us know!
Submit an issue or pull request on the `GitHub repository
<https://github.com/godotengine/godot-docs/issues>`_,
help us `translate the documentation
<https://hosted.weblate.org/engage/godot-engine/>`_ into your
language, or talk to us on the
``#documentation`` channel on the `Godot Contributors Chat
<https://chat.godotengine.org/>`_!
Submit an issue or pull request on the `GitHub repository <https://github.com/godotengine/godot-docs/issues>`_,
help us `translate the documentation <https://hosted.weblate.org/engage/godot-engine/>`_
into your language, or talk to us on the ``#documentation`` channel on the
`Godot Contributors Chat <https://chat.godotengine.org/>`_!
.. centered:: |weblate_widget|
The main documentation for the site is organized into the following sections:
Offline documentation
---------------------
To browse the documentation offline, you can use the mirror of the documentation
hosted on `DevDocs <https://devdocs.io/godot/>`__. To enable offline browsing on
DevDocs, you need to:
- Click the three dots in the top-left corner, choose **Preferences**.
- Enable the desired version of the Godot documentation by checking the box
next to it in the sidebar.
- Click the three dots in the top-left corner, choose **Offline data**.
- Click the **Install** link next to the Godot documentation.
You can also `download an HTML copy <https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip>`__
for offline reading (updated every Monday). Extract the ZIP archive then open
the top-level ``index.html`` in a web browser.
.. Below is the main table-of-content tree of the documentation website.
It is hidden on the page itself, but it makes up the sidebar for navigation.
.. toctree::
:hidden:
:maxdepth: 1
:caption: General
:caption: About
:name: sec-general
about/index
about/introduction
about/faq
about/troubleshooting
about/list_of_features
about/docs_changelog
about/release_policy
about/complying_with_licenses
.. toctree::
:hidden:
:maxdepth: 1
:caption: Getting started
:name: sec-learn
@@ -74,19 +95,23 @@ The main documentation for the site is organized into the following sections:
getting_started/first_3d_game/index
.. The sections below are sorted alphabetically. Please keep them that way.
.. Sections below are split into two groups. First come meta sections, covering
general matters. Below that different areas of the engine are listed.
These sections are sorted alphabetically. Please keep them that way.
.. toctree::
:hidden:
:maxdepth: 1
:caption: Tutorials
:caption: Manual
:name: sec-tutorials
tutorials/best_practices/index
tutorials/editor/index
tutorials/2d/index
tutorials/3d/index
tutorials/animation/index
tutorials/assets_pipeline/index
tutorials/audio/index
tutorials/best_practices/index
tutorials/editor/index
tutorials/export/index
tutorials/i18n/index
tutorials/inputs/index
@@ -106,6 +131,7 @@ The main documentation for the site is organized into the following sections:
.. toctree::
:hidden:
:maxdepth: 1
:caption: Development
:name: sec-devel
@@ -117,6 +143,7 @@ The main documentation for the site is organized into the following sections:
.. toctree::
:hidden:
:maxdepth: 1
:caption: Community
:name: sec-community
@@ -128,16 +155,9 @@ The main documentation for the site is organized into the following sections:
.. toctree::
:hidden:
:maxdepth: 1
:caption: Class reference
:name: sec-class-ref
classes/index
.. Indices and tables
.. ------------------
..
.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`