- Select all existing text in the field when pressing the shortcut.
- Remove broken Algolia integration (unused since 4.0) and move
the shortcut code to the main `custom.js` file.
RTD decided to normalize language codes such as `zh_CN` and `pt_BR`
to `zh-cn` and `pt-br`, apparently because it makes URLs prettier...
https://blog.readthedocs.com/language-codes-are-now-normalized/
But they didn't take into account that Sphinx doesn't do the same,
and still requires `zh_CN` and `pt_BR` for its `language` config value.
So we have to convert it back in `conf.py`, otherwise this breaks our
i18n logic, notably to handle the localized class reference and images.
By default (no flag) articles are considered up-to-date, with the end goal to have no
articles marked as outdated.
Use `:article_outdated: True` at the top of an article to mark it as being outdated.
- General improvements to the page layout and style
- Improved styling for all class (properties, signals, annotations, theme properties, methods, operators, constructors, enumerations, constants)
- Improved styling for tabs, code tabs, standalone code blocks, and tables
This change makes the docs repo always use the official abbreviation (CC BY 3.0)
for its license. Previously, it would sometimes use “CC-BY 3.0” or
“CC-BY-3.0”. This change also make the docs repo always point to the
official Commons deed [1] for more information about CC BY 3.0.
Previously, it would sometimes link to an unofficial source [2].
[1]: <https://creativecommons.org/licenses/by/3.0/>
[2]: <https://tldrlegal.com/license/creative-commons-attribution-(cc)>
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.
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.
Hugo Locurcio