cpp-linter · 2bndy5 · Mar 28, 2024 · Mar 28, 2024
diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css
@@ -25,20 +25,16 @@ thead {
   }
 }
 
-.md-typeset .mdx-heart {
+.md-typeset .mdx-heart::before {
   animation: heart 1s infinite
 }
 
 .md-typeset .mdx-badge {
   font-size: .85em
 }
 
-.md-typeset .mdx-badge--heart {
-  color: #ff4281;
-}
-
-.md-typeset .mdx-badge--heart.twemoji {
-  animation: heart 1s infinite
+.md-typeset .mdx-badge--heart::before {
+  background-color: #ff4281;
 }
 
 .md-typeset .mdx-badge--right {

diff --git a/docs/conf.py b/docs/conf.py
@@ -84,6 +84,7 @@
         "toc.sticky",
         "toc.follow",
         "search.share",
+        "content.tabs.link",
     ],
     "social": [
         {
@@ -153,10 +154,10 @@ def run(self):
             self.rawtext,
             f'<span class="mdx-badge">{head}<span class="mdx-badge__text">'
             + is_linked
-            + (self.text if self.badge_type == "version" else ""),
+            + (self.text if self.badge_type in ["version", "experimental"] else ""),
             format="html",
         )
-        if self.badge_type != "version":
+        if self.badge_type not in ["version", "experimental"]:
             old_highlight = self.inliner.document.settings.syntax_highlight
             self.inliner.document.settings.syntax_highlight = "yaml"
             code, sys_msgs = docutils.parsers.rst.roles.code_role(
@@ -206,6 +207,17 @@ def run(self):
         return super().run()
 
 
+class CliBadgeExperimental(CliBadge):
+    badge_type = "experimental"
+
+    def run(self):
+        self.badge_icon = (
+            load_svg_into_builder_env(self.env.app.builder, "material/flask-outline")
+            + " mdx-badge--heart mdx-heart"
+        )
+        return super().run()
+
+
 REQUIRED_VERSIONS = {
     "1.7.0": ["tidy_review", "format_review"],
     "1.6.1": ["thread_comments", "no_lgtm"],
@@ -215,19 +227,22 @@ def run(self):
 }
 
 PERMISSIONS = {
-    "thread_comments": ["thread-comments", "issues: write"],
+    "thread_comments": ["thread-comments", "contents: write"],
     "tidy_review": ["pull-request-reviews", "pull-requests: write"],
     "format_review": ["pull-request-reviews", "pull-requests: write"],
     "files_changed_only": ["file-changes", "contents: read"],
     "lines_changed_only": ["file-changes", "contents: read"],
 }
 
+EXPERIMENTAL = ["tidy_review"]
+
 
 def setup(app: Sphinx):
     """Generate a doc from the executable script's ``--help`` output."""
     app.add_role("badge-version", CliBadgeVersion())
     app.add_role("badge-default", CliBadgeDefault())
     app.add_role("badge-permission", CliBadgePermission())
+    app.add_role("badge-experimental", CliBadgeExperimental())
 
     doc = "Command Line Interface Options\n==============================\n\n"
     doc += ".. note::\n\n    These options have a direct relationship with the\n    "
@@ -251,6 +266,8 @@ def setup(app: Sphinx):
             req_ver = "1.4.6"
         doc += f"\n    :badge-version:`{req_ver}` "
         doc += f":badge-default:`'{arg.default or ''}'` "
+        if arg.dest in EXPERIMENTAL:
+            doc += ":badge-experimental:`experimental` "
         for name, permission in PERMISSIONS.items():
             if name == arg.dest:
                 link, spec = permission

diff --git a/docs/permissions.rst b/docs/permissions.rst
@@ -4,6 +4,10 @@ Token Permissions
 .. _push events: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push
 .. _pull_request events: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
 
+.. role:: yaml(code)
+  :language: yaml
+  :class: highlight
+
 This is an exhaustive list of required permissions organized by features.
 
 File Changes
@@ -12,31 +16,76 @@ File Changes
 When using :std:option:`--files-changed-only` or :std:option:`--lines-changed-only` to get the list
 of file changes for a CI event, the following permissions are needed:
 
-.. code-block:: yaml
+.. md-tab-set::
 
-    permissions:
-      contents: read # (1)!
+  .. md-tab-item:: :yaml:`on: push`
+
+      For `push events`_
+
+      .. code-block:: yaml
+
+          permissions:
+            contents: read # (1)!
+
+      .. code-annotations::
+
+          #. This permission is also needed to download files if the repository is not checked out before
+             running cpp-linter.
+
+  .. md-tab-item:: :yaml:`on: pull_request`
+
+      For `pull_request events`_
+
+      .. code-block:: yaml
+
+          permissions:
+            contents: read # (1)!
+            pull-requests: read # (2)!
 
-.. code-annotations::
+      .. code-annotations::
 
-    #. This permission is also needed to download files if the repository is not checked out before
-       running cpp-linter (for both push and pull_request events).
+          #. This permission is also needed to download files if the repository is not checked out before
+             running cpp-linter.
+          #. Specifying :yaml:`write` is also sufficient as that is required for
+
+             * posting `thread comments`_ on pull requests
+             * posting `pull request reviews`_
+
+.. _thread comments:
 
 Thread Comments
 ----------------------
 
 The :std:option:`--thread-comments` feature requires the following permissions:
 
-.. code-block:: yaml
+.. md-tab-set::
 
-    permissions:
-      issues: write # (1)!
-      pull-requests: write # (2)!
+  .. md-tab-item:: :yaml:`on: push`
+
+      For `push events`_
+
+      .. code-block:: yaml
+
+          permissions:
+            metadata: read # (1)!
+            contents: write # (2)!
+
+      .. code-annotations::
+
+          #. needed to fetch existing comments
+          #. needed to post or update a commit comment. This also allows us to
+             delete an outdated comment if needed.
+
+  .. md-tab-item:: :yaml:`on: pull_request`
+
+      For `pull_request events`_
+
+      .. code-block:: yaml
 
-.. code-annotations::
+          permissions:
+            pull-requests: write
 
-    #. for `push events`_
-    #. for `pull_request events`_
+.. _pull request reviews:
 
 Pull Request Reviews
 ----------------------