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.
Calinou · Jan 11, 2024 · e7b4dda · e7b4dda
1 parent f6d53d1
commit e7b4dda
Show file tree

Hide file tree

Showing 64 changed files with 147 additions and 2 deletions.
diff --git a/_templates/layout.html b/_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 %}

diff --git a/about/complying_with_licenses.rst b/about/complying_with_licenses.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_complying_with_licenses:
 
 Complying with licenses

diff --git a/about/docs_changelog.rst b/about/docs_changelog.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_docs_changelog:
 
 Documentation changelog

diff --git a/about/faq.rst b/about/faq.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. meta::
     :keywords: FAQ
 

diff --git a/about/introduction.rst b/about/introduction.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_about_intro:
 
 Introduction

diff --git a/about/list_of_features.rst b/about/list_of_features.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_list_of_features:
 
 List of features

diff --git a/about/release_policy.rst b/about/release_policy.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_release_policy:
 
 Godot release policy

diff --git a/community/asset_library/index.rst b/community/asset_library/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Asset Library
 =============
 

diff --git a/conf.py b/conf.py
@@ -196,6 +196,8 @@
     "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"

diff --git a/contributing/development/compiling/index.rst b/contributing/development/compiling/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Building from source
 ====================
 

diff --git a/contributing/development/configuring_an_ide/index.rst b/contributing/development/configuring_an_ide/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_configuring_an_ide:
 
 Configuring an IDE

diff --git a/contributing/development/core_and_modules/index.rst b/contributing/development/core_and_modules/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Engine core and modules
 =======================
 

diff --git a/contributing/development/debugging/index.rst b/contributing/development/debugging/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Debugging and profiling
 =======================
 

diff --git a/contributing/development/debugging/vulkan/index.rst b/contributing/development/debugging/vulkan/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Vulkan
 ======
 

diff --git a/contributing/development/editor/index.rst b/contributing/development/editor/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Editor development
 ==================
 

diff --git a/contributing/development/file_formats/index.rst b/contributing/development/file_formats/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Godot file formats
 ==================
 

diff --git a/contributing/development/index.rst b/contributing/development/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_contributing_to_the_engine:
 
 Engine development

diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_contributing_writing_documentation:
 
 Writing documentation

diff --git a/contributing/workflow/index.rst b/contributing/workflow/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_contributing_workflow:
 
 Contribution workflow

diff --git a/getting_started/first_2d_game/index.rst b/getting_started/first_2d_game/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_your_first_2d_game:
 
 Your first 2D game

diff --git a/getting_started/first_3d_game/index.rst b/getting_started/first_3d_game/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 .. _doc_your_first_3d_game:

diff --git a/getting_started/introduction/index.rst b/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?".

diff --git a/getting_started/step_by_step/index.rst b/getting_started/step_by_step/index.rst
@@ -1,4 +1,4 @@
-:article_outdated: False
+:allow_comments: False
 
 Step by step
 ============

diff --git a/index.rst b/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Godot Docs – *master* branch
 ============================
 

diff --git a/tutorials/2d/index.rst b/tutorials/2d/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 2D
 ==
 

diff --git a/tutorials/3d/global_illumination/index.rst b/tutorials/3d/global_illumination/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_global_illumination:
 
 Global illumination

diff --git a/tutorials/3d/index.rst b/tutorials/3d/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 3D
 ==
 

diff --git a/tutorials/3d/particles/index.rst b/tutorials/3d/particles/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_3d_particles:
 
 Particle systems (3D)

diff --git a/tutorials/3d/procedural_geometry/index.rst b/tutorials/3d/procedural_geometry/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_procedural_geometry:
 
 Procedural geometry

diff --git a/tutorials/animation/index.rst b/tutorials/animation/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Animation
 =========
 

diff --git a/tutorials/assets_pipeline/escn_exporter/index.rst b/tutorials/assets_pipeline/escn_exporter/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Blender ESCN exporter
 =====================
 

diff --git a/tutorials/assets_pipeline/index.rst b/tutorials/assets_pipeline/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Assets pipeline
 ===============
 

diff --git a/tutorials/audio/index.rst b/tutorials/audio/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 :article_outdated: True
 
 Audio

diff --git a/tutorials/best_practices/index.rst b/tutorials/best_practices/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Best practices
 ==============
 

diff --git a/tutorials/editor/index.rst b/tutorials/editor/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Editor introduction

diff --git a/tutorials/export/index.rst b/tutorials/export/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Export
 ======
 

diff --git a/tutorials/i18n/index.rst b/tutorials/i18n/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Internationalization
 ====================
 

diff --git a/tutorials/inputs/index.rst b/tutorials/inputs/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Input handling
 ==============
 

diff --git a/tutorials/io/index.rst b/tutorials/io/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 File and data I/O
 =================
 

diff --git a/tutorials/math/index.rst b/tutorials/math/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Math
 ====
 

diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Migrating to a new version
 ==========================
 

diff --git a/tutorials/navigation/index.rst b/tutorials/navigation/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Navigation
 ==========
 

diff --git a/tutorials/networking/index.rst b/tutorials/networking/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Networking

diff --git a/tutorials/performance/index.rst b/tutorials/performance/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_performance:
 
 Performance

diff --git a/tutorials/performance/vertex_animation/index.rst b/tutorials/performance/vertex_animation/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Animating thousands of objects

diff --git a/tutorials/physics/index.rst b/tutorials/physics/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Physics
 =======
 

diff --git a/tutorials/platform/android/index.rst b/tutorials/platform/android/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Android
 =======
 

diff --git a/tutorials/platform/index.rst b/tutorials/platform/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 Platform-specific

diff --git a/tutorials/platform/ios/index.rst b/tutorials/platform/ios/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 iOS plugins

diff --git a/tutorials/platform/web/index.rst b/tutorials/platform/web/index.rst
@@ -1,3 +1,4 @@
+:allow_comments: False
 :article_outdated: True
 
 .. _doc_platform_html5:

diff --git a/tutorials/plugins/editor/index.rst b/tutorials/plugins/editor/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Editor plugins
 ==============
 

diff --git a/tutorials/plugins/index.rst b/tutorials/plugins/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Plugins
 =======
 

diff --git a/tutorials/rendering/index.rst b/tutorials/rendering/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Rendering
 =========
 

diff --git a/tutorials/scripting/c_sharp/diagnostics/index.rst b/tutorials/scripting/c_sharp/diagnostics/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 .. _doc_c_sharp_diagnostics:
 
 C# diagnostics

diff --git a/tutorials/scripting/c_sharp/index.rst b/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#

diff --git a/tutorials/scripting/debug/index.rst b/tutorials/scripting/debug/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Debug
 =====
 

diff --git a/tutorials/scripting/gdextension/index.rst b/tutorials/scripting/gdextension/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 GDExtension
 ===========
 

diff --git a/tutorials/scripting/gdscript/index.rst b/tutorials/scripting/gdscript/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 GDScript
 ========
 

diff --git a/tutorials/scripting/index.rst b/tutorials/scripting/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Scripting
 =========
 

diff --git a/tutorials/shaders/index.rst b/tutorials/shaders/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Shaders
 =======
 

diff --git a/tutorials/shaders/shader_reference/index.rst b/tutorials/shaders/shader_reference/index.rst
@@ -1,3 +1,5 @@
+:allow_comments: False
+
 Shading reference
 =================
-Original file line number
+Diff line change
@@ -1,3 +1,5 @@
+    :allow_comments: False
     Vulkan
     ======
@@ Expand Down @@