Allow dehardcoding documentation branch and URL in docs links
This makes it possible to change the branch of the documentation that
URLs are pointing to without having to modify all class reference
files.
In the XML class reference, the `$DOCS_URL` placeholder should be used,
and will be replaced automatically in the editor and when generating
the RST class reference.
The documentation branch string is set in `version.py`.
Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro>
(cherry picked from commit 5341e6010e)
This commit is contained in:
Rémi Verschelde
parent
175870ccc7
commit
0cdcf1154f
@ -42,6 +42,7 @@
|
||||
#include "core/translation.h"
|
||||
#include "core/ucaps.h"
|
||||
#include "core/variant.h"
|
||||
#include "core/version_generated.gen.h"
|
||||
|
||||
#include <wchar.h>
|
||||
#include <cstdint>
|
||||
@ -4498,15 +4499,19 @@ String TTR(const String &p_text) {
|
||||
return p_text;
|
||||
}
|
||||
|
||||
/* DTR is used for the documentation, handling descriptions extracted from the XML.
|
||||
* It also replaces `$DOCS_URL` with the actual URL to the documentation's branch,
|
||||
* to allow dehardcoding it in the XML and doing proper substitutions everywhere.
|
||||
*/
|
||||
String DTR(const String &p_text) {
|
||||
// Comes straight from the XML, so remove indentation and any trailing whitespace.
|
||||
const String text = p_text.dedent().strip_edges();
|
||||
|
||||
if (TranslationServer::get_singleton()) {
|
||||
return TranslationServer::get_singleton()->doc_translate(text);
|
||||
return String(TranslationServer::get_singleton()->doc_translate(text)).replace("$DOCS_URL", VERSION_DOCS_URL);
|
||||
}
|
||||
|
||||
return text;
|
||||
return text.replace("$DOCS_URL", VERSION_DOCS_URL);
|
||||
}
|
||||
#endif
|
||||
|
||||
|
||||
@ -11,10 +11,8 @@ from collections import OrderedDict
|
||||
# Uncomment to do type checks. I have it commented out so it works below Python 3.5
|
||||
# from typing import List, Dict, TextIO, Tuple, Iterable, Optional, DefaultDict, Any, Union
|
||||
|
||||
# http(s)://docs.godotengine.org/<langcode>/<tag>/path/to/page.html(#fragment-tag)
|
||||
GODOT_DOCS_PATTERN = re.compile(
|
||||
r"^http(?:s)?://docs\.godotengine\.org/(?:[a-zA-Z0-9.\-_]*)/(?:[a-zA-Z0-9.\-_]*)/(.*)\.html(#.*)?$"
|
||||
)
|
||||
# $DOCS_URL/path/to/page.html(#fragment-tag)
|
||||
GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$")
|
||||
|
||||
|
||||
def print_error(error, state): # type: (str, State) -> None
|
||||
@ -728,16 +726,11 @@ def rstize_text(text, state): # type: (str, State) -> str
|
||||
|
||||
# Handle [tags]
|
||||
inside_code = False
|
||||
inside_url = False
|
||||
url_has_name = False
|
||||
url_link = ""
|
||||
pos = 0
|
||||
tag_depth = 0
|
||||
previous_pos = 0
|
||||
while True:
|
||||
pos = text.find("[", pos)
|
||||
if inside_url and (pos > previous_pos):
|
||||
url_has_name = True
|
||||
if pos == -1:
|
||||
break
|
||||
|
||||
@ -856,17 +849,23 @@ def rstize_text(text, state): # type: (str, State) -> str
|
||||
elif cmd.find("image=") == 0:
|
||||
tag_text = "" # ''
|
||||
elif cmd.find("url=") == 0:
|
||||
url_link = cmd[4:]
|
||||
tag_text = "`"
|
||||
tag_depth += 1
|
||||
inside_url = True
|
||||
url_has_name = False
|
||||
elif cmd == "/url":
|
||||
tag_text = ("" if url_has_name else url_link) + " <" + url_link + ">`__"
|
||||
tag_depth -= 1
|
||||
escape_post = True
|
||||
inside_url = False
|
||||
url_has_name = False
|
||||
# URLs are handled in full here as we need to extract the optional link
|
||||
# title to use `make_link`.
|
||||
link_url = cmd[4:]
|
||||
endurl_pos = text.find("[/url]", endq_pos + 1)
|
||||
if endurl_pos == -1:
|
||||
print_error(
|
||||
"Tag depth mismatch for [url]: no closing [/url], file: {}".format(state.current_class), state
|
||||
)
|
||||
break
|
||||
link_title = text[endq_pos + 1 : endurl_pos]
|
||||
tag_text = make_link(link_url, link_title)
|
||||
|
||||
pre_text = text[:pos]
|
||||
text = pre_text + tag_text + text[endurl_pos + 6 :]
|
||||
pos = len(pre_text) + len(tag_text)
|
||||
previous_pos = pos
|
||||
continue
|
||||
elif cmd == "center":
|
||||
tag_depth += 1
|
||||
tag_text = ""
|
||||
@ -1081,21 +1080,22 @@ def make_link(url, title): # type: (str, str) -> str
|
||||
if match.lastindex == 2:
|
||||
# Doc reference with fragment identifier: emit direct link to section with reference to page, for example:
|
||||
# `#calling-javascript-from-script in Exporting For Web`
|
||||
return "`" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`_ in :doc:`../" + groups[0] + "`"
|
||||
# Commented out alternative: Instead just emit:
|
||||
# `Subsection in Exporting For Web`
|
||||
# return "`Subsection <../" + groups[0] + ".html" + groups[1] + ">`__ in :doc:`../" + groups[0] + "`"
|
||||
# Or use the title if provided.
|
||||
if title != "":
|
||||
return "`" + title + " <../" + groups[0] + ".html" + groups[1] + ">`__"
|
||||
return "`" + groups[1] + " <../" + groups[0] + ".html" + groups[1] + ">`__ in :doc:`../" + groups[0] + "`"
|
||||
elif match.lastindex == 1:
|
||||
# Doc reference, for example:
|
||||
# `Math`
|
||||
if title != "":
|
||||
return ":doc:`" + title + " <../" + groups[0] + ">`"
|
||||
return ":doc:`../" + groups[0] + "`"
|
||||
else:
|
||||
# External link, for example:
|
||||
# `http://enet.bespin.org/usergroup0.html`
|
||||
if title != "":
|
||||
return "`" + title + " <" + url + ">`__"
|
||||
else:
|
||||
return "`" + url + " <" + url + ">`__"
|
||||
return "`" + url + " <" + url + ">`__"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
@ -32,13 +32,14 @@
|
||||
|
||||
#include "core/os/input.h"
|
||||
#include "core/os/keyboard.h"
|
||||
#include "core/version_generated.gen.h"
|
||||
#include "doc_data_compressed.gen.h"
|
||||
#include "editor/plugins/script_editor_plugin.h"
|
||||
#include "editor_node.h"
|
||||
#include "editor_scale.h"
|
||||
#include "editor_settings.h"
|
||||
|
||||
#define CONTRIBUTE_URL "https://docs.godotengine.org/en/latest/community/contributing/updating_the_class_reference.html"
|
||||
#define CONTRIBUTE_URL vformat("%s/community/contributing/updating_the_class_reference.html", VERSION_DOCS_URL)
|
||||
|
||||
DocData *EditorHelp::doc = nullptr;
|
||||
|
||||
|
||||
@ -34,6 +34,7 @@
|
||||
#include "core/io/resource_saver.h"
|
||||
#include "core/os/keyboard.h"
|
||||
#include "core/os/os.h"
|
||||
#include "core/version_generated.gen.h"
|
||||
#include "editor/editor_node.h"
|
||||
#include "editor/editor_scale.h"
|
||||
#include "editor/editor_settings.h"
|
||||
@ -337,7 +338,7 @@ void ShaderEditor::_menu_option(int p_option) {
|
||||
shader_editor->remove_all_bookmarks();
|
||||
} break;
|
||||
case HELP_DOCS: {
|
||||
OS::get_singleton()->shell_open("https://docs.godotengine.org/en/3.4/tutorials/shading/shading_reference/index.html");
|
||||
OS::get_singleton()->shell_open(vformat("%s/tutorials/shaders/shader_reference/index.html", VERSION_DOCS_URL));
|
||||
} break;
|
||||
}
|
||||
if (p_option != SEARCH_FIND && p_option != SEARCH_REPLACE && p_option != SEARCH_GOTO_LINE) {
|
||||
|
||||
@ -88,6 +88,8 @@ def update_version(module_version_string=""):
|
||||
f.write('#define VERSION_MODULE_CONFIG "' + str(version.module_config) + module_version_string + '"\n')
|
||||
f.write("#define VERSION_YEAR " + str(version.year) + "\n")
|
||||
f.write('#define VERSION_WEBSITE "' + str(version.website) + '"\n')
|
||||
f.write('#define VERSION_DOCS_BRANCH "' + str(version.docs) + '"\n')
|
||||
f.write('#define VERSION_DOCS_URL "https://docs.godotengine.org/en/" VERSION_DOCS_BRANCH\n')
|
||||
f.close()
|
||||
|
||||
# NOTE: It is safe to generate this file here, since this is still executed serially
|
||||
|
||||
@ -7,3 +7,4 @@ status = "beta"
|
||||
module_config = ""
|
||||
year = 2021
|
||||
website = "https://godotengine.org"
|
||||
docs = "3.4"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user