The readthedocs-sphinx-search extension is not actively maintained upstream,
and they pin some extremely old versions of Sphinx components which are not
compatible with what we need to use.
It was already dropped in the master branch, this syncs the requirements.txt
from master with 3.4.
It will look up a potential `classes/<lang>` folder in the parent repository
of https://github.com/godotengine/godot-docs-l10n and use it if provided.
This folder includes a pre-translated copy of the class reference XML, read
to be used by Sphinx. This turned out to be a simpler approach than generating
PO files for class reference strings in reStructured Text format, given that
their source format is XML and the conversion on a per `msgid` basis would be
quite tricky.
This approach is very hacky, as Sphinx doesn't seem to support any kind of
conditional statements in its `toctree` directives, so we have to outright
replace the content at build time. This should typically only be done on RTD
so it shouldn't end up polluting the Git history.
(cherry picked from commit a29b557361)
This is provided by the sphinxext-opengraph extension.
This also adds a theme color property in the HTML layout file.
(cherry picked from commit 9becaa5480)
Adding the compatibility notice via JavaScript prevents the
`meta description` Sphinx extension from taking the notice
as part of the description.
This also changes the redirect URL to point to the page the user
is currently reading instead of always pointing to the homepage.
Not everything in the `latest` branch applies to Godot 3.2.x.
Read the Docs adds a warning notice for old versions automatically,
but it doesn't offer an option to do so for the `latest`/unstable
branch so we have to add it ourselves.
It's the only tutorial where we used the extension for *3* formulas which anyway
ended up as fairly low res static images generated by sphinx.ext.imgmath, so
requiring ~1 GB of LaTeX setup for it is overkill.
The replacement pictures are the ones generated by sphinx.ext.imgmath, we could
replace them by higher resolution ones.
Smartquotes will convert '"..."' to '“...”', will cause unexpected
result when we reference a string without using code block.
also in some languages (zh_TW for example), it will be converted to
'「...」', usually not a desired result.
Improve CI build times by using a dummy builder for (empty) output, dropping LaTeX, and disabling some Sphinx extensions when building for CI (GDScript lexing, creating a search index, and generating HTML description tags).
In my tests, this improves Travis CI build times: from up to 30 minutes down to 2 minutes.
The localization for this documentation is handled via the godot-docs-l10n
repository at: https://github.com/godotengine/godot-docs-l10n
Sphinx supports localization of images by automatically looking up files
with a language code suffix (e.g. `myimage.zh_CN.png` as an override for
`myimage.png` when using `zh_CN` locale), but only in the same location as
the original file.
We want to host our localized images together with the PO files in the l10n
repo, so we use a glorious hack to redefine Sphinx's
`sphinx.util.i18n.get_image_filename_for_language` method in a way that fits
our needs.
Fixesgodotengine/godot-docs-l10n#5.
Co-authored-by: BinotaLIU <binota@binota.org>
Co-authored-by: Gilles Roudiere <gilles.roudiere@gmail.com>
I couldn't find how to make the `html_title` value translatable using
sphinx-gettext (tried `sphinx.locale._()` but it wouldn't extract it),
so I'm hardcoding translations for now.
This hopefully fixes all translated pages showing up in search engine results, and makes the STABLE version of each page canonical.
In turn, this allows us to re-enable indexing of the version-specific pages (see robots.txt changes), as search engines should prefer the canonical (stable) version, and only show the other versions if no canonical (stable) version exists (i.e. because that feature is only in latest, or was removed in stable).
It adds proper canonical links for all generated pages, and fixes the existing links between the various translations of a page by both ensuring the pages links to itself with the proper language tag, and by properly linking to the full path of other translated versions.
This also adds a missing comma in the middle of the list of
built-in types. The `name`, `funcname` and `classname` were also
missing a `r` qualifier, so it was added.
Commands used for formatting and linting:
black conf.py extensions/gdscript.py
flake8 --ignore E501 conf.py extensions/gdscript.py
This also removes the need to load Web fonts, leading to a smoother
page loading experience.
Co-authored-by: Nicholas Hydock <nhydock@users.noreply.github.com>
This commit provides two small fixes.
Gif images are not supported by latexpdf. There are a handful of options
to resolve that issue, but the already-available imgconverter extension
takes care of converting them to supported image formats.
The pdf build was failing due to the deprecated Sphinx `app.warn` used
in the sphinx_tabs extension. The `app.log` deprecation was already
handled in this function, and now `warn` is as well.
ReadTheDocs properly overrides `language` via's sphinx-build's
`-D language=value` parameter, but when we do the initial parsing
of `conf.py` it still uses the original value, so our custom logic
for Weblate badges was not working.
Up until now I mistakenly thought that ReadTheDocs' tags
were the same as Sphinx tags, and would be passed to the
build. It turns out that aren't, so our `.. only:: i18n`
logic did not work.
Instead, we now use RTD environment variables to pass
comma-separated tags to Sphinx.
It will now show the translation status for the used language instead
of the overall completion for all languages.
The badge widget's text is also in the used language.
The drawback is that to do this I had to inject the localized image
directive in the `rst_epilog` for all pages, even though we only need
it for the index.
