Add support for user-provided comments with Giscus

[Calinou]

In a fashion similar to https://php.net's comments, 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.

More details can be found in the User-contributed notes policy I've written.

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.0 to "see" each other in discussions.

See https://giscus.app for more information.

• See Embed QA into documentation pages godot-proposals#481.

TODO

• Add :allow_comments: False on all index/listing pages.
• Modify makerst.py in the main Godot repository to write :allow_comments: False at the top of classes/index.rst, as was done manually here. makerst: Disallow user-contributed notes on the class index page godot#85006
• Set up Discussions on godotengine/godot-docs godotengine/godot-docs-user-notes and use the Giscus setup form again, so that the discussion category unique ID is updated. Use the following options, with "Calinou/godot-docs" replaced by "godotengine/godot-docs".
  • Rename the default Announcements category to Page comments while keeping its type on Announcements. Change its emoji to 🗨️. Remove all other categories, so that users cannot create discussions manually (the Giscus app will do it for them).
  • Create a second category called Rules with the Announcements type and 📏 emoji.
  • Create a post called "User-contributed notes policy" in the Rules category with the contents from https://github.com/Calinou/godot-docs/discussions/46, then pin the post globally (not in a single category) and lock it. Make sure reactions are not allowed when locking the post. Use the Markdown code below.
• Replace URL to the User-contributed notes policy in layout.html to point to godot-docs' version, rather than the Calinou fork.

Preview

https://github.com/godotengine/godot-docs-user-notes/discussions

Example at the bottom of the 3D text page

The theme follows the system theme, which means it'll adapt to the documentation's theme automatically.

Footnotes

1. We can choose to use a dedicated repository containing just discussions if we wish to do so. ↩

[mhilbrunner]

The User-contributed notes policy seems good. I'd maybe change the bit about licensing to maybe say in the docs and the Godot project/engine, and try to link to existing license pages for both instead of mentioning any specific license, but not sure.

We should also consider making sure this does not work in local dev builds and in forks by default unless you toggle something, otherwise if another random docs website mirror appears, I could see that lead to confusion. Same for translations - if a page in a non-english translation has no comments yet, it may be too easy to just leave a comment in whatever native language, becoming confusing for other users.

Also need to check how reporting/moderation would work.

I'm also less sure whether we should bother adding this to 3.x docs at all. Everything worth discussing in 3.x has probably already been discussed ad nauseam elsewhere, and we don't get many 3.x docs PRs these days, so I assume most things at this point in time are mostly complete and in a good shape, mature as 3.x is. So I could see the confusion between comments between 2 major versions outweigh the benefit.

Besides those small need-to-check TODOs, this looks good to me and it has my stamp of approval.

[Calinou]

I'd maybe change the bit about licensing to maybe say in the docs and the Godot project/engine, and try to link to existing license pages for both instead of mentioning any specific license, but not sure.

We don't have the documentation license listed on godotengine.org/license, but I've changed the wording to also mention the engine itself and its license.

We should also consider making sure this does not work in local dev builds and in forks by default unless you toggle something, otherwise if another random docs website mirror appears, I could see that lead to confusion. Same for translations - if a page in a non-english translation has no comments yet, it may be too easy to just leave a comment in whatever native language, becoming confusing for other users.

I've changed it to disable comments integration if not building on Read the Docs, and if the language isn't English. I'm not sure what would be the best way to disable it in forks automatically, preferably at build-time in conf.py.

I'm also less sure whether we should bother adding this to 3.x docs at all. Everything worth discussing in 3.x has probably already been discussed ad nauseam elsewhere, and we don't get many 3.x docs PRs these days, so I assume most things at this point in time are mostly complete and in a good shape, mature as 3.x is. So I could see the confusion between comments between 2 major versions outweigh the benefit.

I agree with making it 4.x-only.

[mhilbrunner]

I'm not sure what would be the best way to disable it in forks automatically, preferably at build-time in conf.py.

Yeah, a build var similar to godot_show_article_status in conf.py, but default to false and overridable via an environment var would be easiest (we can set custom env vars in the RTD dashboard).

[Calinou]

Yeah, a build var similar to godot_show_article_status in conf.py, but default to false and overridable via an environment var would be easiest (we can set custom env vars in the RTD dashboard).

I've added show_article_comments which defaults to on_rtd and not is_i18n in conf.py. This means it's enabled automatically when building on RTD, and only for English.

[Calinou]

I've performed repository setup on https://github.com/godotengine/godot-docs-user-notes.

I'll look into updating makerst.py, then we can sync the class reference (just to make sure it works) and merge this PR.

Edit: Done 🙂

[Calinou]

Rebased and tested again, it works as expected. Pages in the About section no longer allow comments too.

[mhilbrunner]

Thanks for working on this! Let's see how this works out.