This allows users to leave comments on pages that don't have
`:allow_comments: False` somewhere in the page's source.
Both manual and class reference pages can receive comments.
Index pages cannot have comments, as discussion should occur on "leaf" pages.
GitHub Discussions is used as a backend on the same repository. This means
that Discussions *must* be enabled on godotengine/godot-docs before this
commit is merged to `master`. Users can choose to use the "Custom" watch
mode if they don't want to get notifications for discussion updates,
but still get notifications for issue and pull request updates.
User comments are intended to be used for the following purposes:
- Add a clarification or correct something in the documentation,
without having to open a pull request. Contributors are encouraged to
take a look at discussions from time to time, and see if there's information
worth incorporating in the pages themselves. Don't forget to reply to
the comment when doing so :)
- Mention a workaround for a common issue.
- Link to useful third-party resources that are relevant to the current page,
such as tutorials or add-ons.
User comments should *not* be used for technical support. Other community
platforms should be used for that.
Page-to-discussion matching is done using the `pagename` Sphinx variable,
which is independent of the Godot version and documentation language.
Being independent of the Godot version allows keeping old comments
when the Godot version changes, while also allowing users from `/stable`
and `/4.1` to "see" each other in discussions.
See https://giscus.app for more information.
- 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.
Max Hilbrunner