Add support for user-provided comments with Giscus

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.

_templates/layout.html

@@ -66,6 +66,35 @@
   {% endif %}
 
   {% block body %}{% endblock %}
+
+{% if (not meta or meta.get('allow_comments') != 'False') and godot_show_article_comments %}
+<hr>
+<h2>User-contributed notes</h2>
+<p>
+  <em>Please read the <a href="https://github.com/godotengine/godot-docs-user-notes/discussions/1">User-contributed notes policy</a> before submitting a comment.</em>
+</p>
+{# Use https://giscus.app/ to regenerate the script tag if needed. #}
+{# data-term is set to be language-independent and version-independent, so that comments can be centralized for each page. #}
+{# This increases the likelihood that users will encounter comments on less frequently visited pages. #}
+<script src="https://giscus.app/client.js"
+  data-repo="godotengine/godot-docs-user-notes"
+  data-repo-id="R_kgDOKuNx0w"
+  data-category="User-contributed notes"
+  data-category-id="DIC_kwDOKuNx084CbANb"
+  data-mapping="specific"
+  data-term="{{ pagename }}"
+  data-strict="1"
+  data-reactions-enabled="0"
+  data-emit-metadata="0"
+  data-input-position="bottom"
+  data-theme="preferred_color_scheme"
+  data-lang="en"
+  data-loading="lazy"
+  crossorigin="anonymous"
+  async></script>
+<br>
+{% endif %}
+
 {%- if self.comments()|trim %}
   <div class="articleComments">
     {%- block comments %}{% endblock %}

about/complying_with_licenses.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_complying_with_licenses:
 
 Complying with licenses

about/docs_changelog.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_docs_changelog:
 
 Documentation changelog

about/faq.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. meta::
     :keywords: FAQ
 

about/introduction.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_about_intro:
 
 Introduction

about/list_of_features.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_list_of_features:
 
 List of features

about/release_policy.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_release_policy:
 
 Godot release policy

community/asset_library/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Asset Library
 =============
 

conf.py

@@ -196,6 +196,8 @@ html_context = {
     "godot_version": "4.3",
     # Enables a banner that displays the up-to-date status of each article.
     "godot_show_article_status": True,
+    # Display user-contributed notes at the bottom of pages that don't have `:allow_comments: False` at the top.
+    "godot_show_article_comments": on_rtd and not is_i18n,
 }
 
 html_logo = "img/docs_logo.svg"

contributing/development/compiling/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Building from source
 ====================
 

contributing/development/configuring_an_ide/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_configuring_an_ide:
 
 Configuring an IDE

contributing/development/core_and_modules/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Engine core and modules
 =======================
 

contributing/development/debugging/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Debugging and profiling
 =======================
 

contributing/development/debugging/vulkan/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Vulkan
 ======
 

contributing/development/editor/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Editor development
 ==================
 

contributing/development/file_formats/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Godot file formats
 ==================
 

contributing/development/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_contributing_to_the_engine:
 
 Engine development

contributing/documentation/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_contributing_writing_documentation:
 
 Writing documentation

contributing/workflow/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_contributing_workflow:
 
 Contribution workflow

getting_started/first_2d_game/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_your_first_2d_game:
 
 Your first 2D game

getting_started/first_3d_game/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 .. _doc_your_first_3d_game:

getting_started/introduction/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. Intention: provide the necessary information to make the most of the getting
    started series, answering questions like "do I want to learn Godot?", "how
    does it look and feel?", "how does it work?", and "how do I best learn it?".

getting_started/step_by_step/index.rst

@@ -1,4 +1,4 @@
-:article_outdated: False
+:allow_comments: False
 
 Step by step
 ============

index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Godot Docs – *master* branch
 ============================
 

tutorials/2d/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 2D
 ==
 

tutorials/3d/global_illumination/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_global_illumination:
 
 Global illumination

tutorials/3d/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 3D
 ==
 

tutorials/3d/particles/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_3d_particles:
 
 Particle systems (3D)

tutorials/3d/procedural_geometry/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_procedural_geometry:
 
 Procedural geometry

tutorials/animation/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Animation
 =========
 

tutorials/assets_pipeline/escn_exporter/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Blender ESCN exporter
 =====================
 

tutorials/assets_pipeline/importing_3d_scenes/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_importing_3d_scenes:
 
 Importing 3D scenes

tutorials/assets_pipeline/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Assets pipeline
 ===============
 

tutorials/audio/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 :article_outdated: True
 
 Audio

tutorials/best_practices/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Best practices
 ==============
 

tutorials/editor/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Editor introduction

tutorials/export/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Export
 ======
 

tutorials/i18n/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Internationalization
 ====================
 

tutorials/inputs/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Input handling
 ==============
 

tutorials/io/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 File and data I/O
 =================
 

tutorials/math/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Math
 ====
 

tutorials/migrating/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Migrating to a new version
 ==========================
 

tutorials/navigation/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Navigation
 ==========
 

tutorials/networking/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Networking

tutorials/performance/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_performance:
 
 Performance

tutorials/performance/vertex_animation/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Animating thousands of objects

tutorials/physics/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Physics
 =======
 

tutorials/platform/android/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Android
 =======
 

tutorials/platform/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Platform-specific

tutorials/platform/ios/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 iOS plugins

tutorials/platform/web/index.rst

@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 .. _doc_platform_html5:

tutorials/plugins/editor/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Editor plugins
 ==============
 

tutorials/plugins/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Plugins
 =======
 

tutorials/rendering/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Rendering
 =========
 

tutorials/scripting/c_sharp/diagnostics/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_c_sharp_diagnostics:
 
 C# diagnostics

tutorials/scripting/c_sharp/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 C#/.NET
 =======
 
@@ -8,7 +10,6 @@ The standard Godot executable does not contain C# support out of the box. Instea
 to enable C# support for your project you need to `download a .NET version <https://godotengine.org/download/>`_
 of the editor from the Godot website.
 
-
 .. toctree::
    :maxdepth: 1
    :name: toc-learn-scripting-C#

tutorials/scripting/debug/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Debug
 =====
 

tutorials/scripting/gdextension/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 GDExtension
 ===========
 

tutorials/scripting/gdscript/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 GDScript
 ========
 

tutorials/scripting/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Scripting
 =========
 

tutorials/shaders/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Shaders
 =======
 

tutorials/shaders/shader_reference/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Shading reference
 =================
 

tutorials/shaders/your_first_shader/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Your first shader
 =================
 

tutorials/ui/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_user_interface:
 
 User interface (UI)

tutorials/xr/index.rst

@@ -1,3 +1,5 @@
+:allow_comments: False
+
 XR
 ==