Merge pull request #56127 from akien-mga/doc-makerst-lang-headings

This commit is contained in:
Rémi Verschelde 2021-12-21 14:39:02 +01:00 committed by GitHub
commit d3d6208ec8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 59 additions and 6 deletions

View File

@ -3,6 +3,8 @@ CLASSES = $(BASEDIR)/classes/ $(BASEDIR)/../modules/
OUTPUTDIR = $(BASEDIR)/_build
TOOLSDIR = $(BASEDIR)/tools
JSDIR = $(BASEDIR)/../platform/javascript
LANGARG ?= en
LANGCMD = -l $(LANGARG)
.ONESHELL:
@ -17,7 +19,7 @@ doxygen:
rst:
rm -rf $(OUTPUTDIR)/rst
mkdir -p $(OUTPUTDIR)/rst
python3 $(TOOLSDIR)/make_rst.py -o $(OUTPUTDIR)/rst $(CLASSES)
python3 $(TOOLSDIR)/make_rst.py -o $(OUTPUTDIR)/rst $(LANGCMD) $(CLASSES)
rstjs:
rm -rf $(OUTPUTDIR)/rstjs

View File

@ -19,6 +19,28 @@ GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$")
MARKUP_ALLOWED_PRECEDENT = " -:/'\"<([{"
MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>"
# Used to translate the section headings when required with --lang argument.
# The HEADINGS list should be synced with what we actually write with `make_heading`,
# and also hardcoded in `doc/translations/extract.py`.
HEADINGS = [
"Description",
"Tutorials",
"Properties",
"Constructors",
"Methods",
"Operators",
"Theme Properties",
"Signals",
"Enumerations",
"Constants",
"Property Descriptions",
"Constructor Descriptions",
"Method Descriptions",
"Operator Descriptions",
"Theme Property Descriptions",
]
headings_l10n = {}
def print_error(error, state): # type: (str, State) -> None
print("ERROR: {}".format(error))
@ -367,6 +389,7 @@ def main(): # type: () -> None
parser = argparse.ArgumentParser()
parser.add_argument("path", nargs="+", help="A path to an XML file or a directory containing XML files to parse.")
parser.add_argument("--filter", default="", help="The filepath pattern for XML files to filter.")
parser.add_argument("--lang", "-l", default="en", help="Language to use for section headings.")
group = parser.add_mutually_exclusive_group()
group.add_argument("--output", "-o", default=".", help="The directory to save output .rst files in.")
group.add_argument(
@ -376,6 +399,25 @@ def main(): # type: () -> None
)
args = parser.parse_args()
# Retrieve heading translations for the given language.
if not args.dry_run and args.lang != "en":
lang_file = os.path.join(
os.path.dirname(os.path.realpath(__file__)), "..", "translations", "{}.po".format(args.lang)
)
if os.path.exists(lang_file):
try:
import polib
except ImportError:
print("Section heading localization requires `polib`.")
exit(1)
pofile = polib.pofile(lang_file)
for entry in pofile.translated_entries():
if entry.msgid in HEADINGS:
headings_l10n[entry.msgid] = entry.msgstr
else:
print("No PO file at '{}' for language '{}'.".format(lang_file, args.lang))
print("Checking for errors in the XML class reference...")
file_list = [] # type: List[str]
@ -467,7 +509,7 @@ def make_rst_class(class_def, state, dry_run, output_dir): # type: (ClassDef, S
f.write(".. The source is found in doc/classes or modules/<name>/doc_classes.\n\n")
f.write(".. _class_" + class_name + ":\n\n")
f.write(make_heading(class_name, "="))
f.write(make_heading(class_name, "=", False))
# Inheritance tree
# Ascendants
@ -1261,7 +1303,11 @@ def make_method_signature(
return ret_type, out
def make_heading(title, underline): # type: (str, str) -> str
def make_heading(title, underline, l10n=True): # type: (str, str, bool) -> str
if l10n:
if title in headings_l10n:
title = headings_l10n.get(title)
underline *= 2 # Double length to handle wide chars.
return title + "\n" + (underline * len(title)) + "\n\n"

View File

@ -26,17 +26,22 @@ msgstr ""
"""
# Some strings used by make_rst.py are normally part of the editor translations,
# so we need to include them manually here for the online docs.
BASE_STRINGS = [
HEADINGS = [
"Description",
"Tutorials",
"Properties",
"Constructors",
"Methods",
"Operators",
"Theme Properties",
"Signals",
"Enumerations",
"Constants",
"Property Descriptions",
"Constructor Descriptions",
"Method Descriptions",
"Operator Descriptions",
"Theme Property Descriptions",
]
## <xml-line-number-hack from="https://stackoverflow.com/a/36430270/10846399">
@ -224,12 +229,12 @@ def _make_translation_catalog(classes):
def _generate_translation_catalog_file(unique_msgs, output, location_line=False):
with open(output, "w", encoding="utf8") as f:
f.write(HEADER)
for msg in BASE_STRINGS:
for msg in HEADINGS:
f.write("#: doc/tools/make_rst.py\n")
f.write('msgid "{}"\n'.format(msg))
f.write('msgstr ""\n\n')
for msg in unique_msgs:
if len(msg) == 0 or msg in BASE_STRINGS:
if len(msg) == 0 or msg in HEADINGS:
continue
f.write("#:")