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.
4-space is our convention for indented blocks and should be used consistently.
The only exception is for C++ code which is tab-indented, as the engine code.
Though it covers an interesting topic in a way that can be beneficial
to many Godot users, after discussion with doc team members and reduz
we feel that its current scope is too out of phase with the target
readership of the Godot docs.
This tutorial would work better hosted out of the Godot docs, and
referenced with a `.. seealso::` link for those who want to dig further
into the math meat.
Thanks a lot to tagcup for this contribution though (as well as the
many contributions to the engine's math and rendering), and sorry for
not better describing what kind of "advanced" math tutorial would be
fitting for the Godot docs.
Sphinx: Also reverted from mathjax to imgmath, as the former implied
running JS code on every single page (regardless of their use of LaTeX
formulas to renderer), so for now imgmath is simpler and good enough.
