Merge pull request #50 from Ivorforce/easy-team-links

Add a custom role for team links

_extensions/godot_areas.py

@@ -1,9 +1,11 @@
 """
 A directive for organization/areas.rst to render the area tables.
 """
+import dataclasses
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
+from sphinx.roles import XRefRole
 import re
 
 area_table_rows = ("Communication", "GitHub reviews", "GitHub labels", "Triage project", "Maintainers")
@@ -88,5 +90,38 @@ class TableDirective(Directive):
         return [table]
 
 
+class TeamRole(XRefRole):
+    def __init__(self):
+        self.is_patched: bool = False
+        self.title: str = ""
+        self.role: str = ""
+
+        super().__init__()
+
+    def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
+        # Hacky, but apparently easiest way to get normal link behavior.
+        if not self.is_patched:
+            role = self.target.lower().replace(" ", "_")
+
+            if self.has_explicit_title:
+                self.title = f"◆ {self.title}"
+            else:
+                title = f"◆ {self.title} team"
+
+            self.target = f"team_{role}"
+            self.has_explicit_title = True
+
+            self.is_patched = True
+
+        self.refdomain, self.reftype = "std", "ref"
+        self.classes = ['xref', self.reftype]
+
+        if self.disabled:
+            return self.create_non_xref_node()
+        else:
+            return self.create_xref_node()
+
+
 def setup(app):
     app.add_directive('gdareatable', TableDirective)
+    app.add_role('team', TeamRole())

conf.py

@@ -21,7 +21,7 @@ extensions = [
     "sphinxext.opengraph",
     "sphinx_copybutton",
     "sphinxcontrib.video",
-    "area_table",
+    "godot_areas",
     "gdscript",
 ]
 

documentation/guidelines/content_guidelines.rst

@@ -31,7 +31,7 @@ should ensure that we cover everything Godot does.
 
 .. note::
 
-    When adding or updating an engine feature, the documentation team needs to
+    When adding or updating an engine feature, the :team:`Documentation` needs to
     know about it. Contributors should open an issue on the `godot-docs` repository
     when their work gets merged and requires documentation.
 
@@ -72,7 +72,7 @@ could be considered part of the official API. This means that documenting uninte
 rely on things that might need to be changed in the future, limiting what we can change without breaking compatibility.
 
 To avoid accidentally documenting unintended behavior, :ref:`area maintainers <doc_areas>` should always review
-changes to the documentation of their respective area. The documentation team should help organizing this and with
+changes to the documentation of their respective area. The :team:`Documentation` should help organizing this and with
 writing when needed.
 
 These rules are not absolute, but are usually correct. If you are unsure what to document, don't hesitate to ask the

organization/areas.rst

@@ -124,6 +124,8 @@ Demos
    :github_reviews: @godotengine/demos
    :maintainers: <lead>Aaron Franke (@aaronfranke)</lead>, Ilaria Cislaghi (@QbieShay), K. S. Ernest Lee (@fire), Rémi Verschelde (@akien-mga)
 
+.. _team_documentation:
+
 Documentation
 -------------
 
@@ -287,6 +289,8 @@ for their area.
    :github_labels: <gh-label>topic:tests</gh-label>
    :maintainers: Hugo Locurcio (@Calinou), Gordon MacPherson (@RevoluPowered), Hendrik Brucker (@Geometror), Rémi Verschelde (@akien-mga)
 
+.. _team_triage:
+
 Bugsquad / Issue triage
 ~~~~~~~~~~~~~~~~~~~~~~~
 

organization/how_to_contribute.rst

@@ -87,7 +87,7 @@ Participate in Godot's development
   `Weblate <https://hosted.weblate.org/projects/godot-engine/godot/>`__.
 
 - **Bugsquad & triage**
-  With so many bug reports and pull requests being opened each day, the triage team — also called bugsquad — is
+  With so many bug reports and pull requests being opened each day, the :team:`Triage` — also called bugsquad — is
   invaluable to keep things organized.
   If you'd like to get involved, please visit :ref:`doc_bug_triage_intro`!
 

other/triage/guidelines.rst

@@ -3,11 +3,11 @@
 Bug triage guidelines
 =====================
 
-This page describes the typical workflow of the bug triage team aka
+This page describes the typical workflow of the :team:`Triage` aka
 bugsquad when handling issues and pull requests on Godot's
 `GitHub repository <https://github.com/godotengine/godot>`__.
 It is bound to evolve together with the bugsquad, so do not
-hesitate to propose modifications to the following guidelines.
+hesitate to propose modifications to the following guidelines
 
 Issues management
 -----------------

other/triage/index.rst

@@ -1,7 +1,7 @@
 Bugsquad and triage
 ===================
 
-This section explains the workflow and guidelines of the :ref:`triage team <doc_areas>`.
+This section explains the workflow and guidelines of the :team:`Triage`.
 
 .. toctree::
    :maxdepth: 1

pull_requests/pr_workflow.rst

@@ -28,7 +28,7 @@ following:
   2. A contributor :ref:`opens a pull request <doc_creating_pull_requests>` that addresses the issue
      or implements the idea.
 
-  3. The :ref:`bugsquad and triage team <doc_areas>` **categorize** the pull request,
+  3. The :team:`Bugsquad and triage team <triage>` **categorize** the pull request,
      adding appropriate tags and requesting reviews from :ref:`area maintainers <doc_areas>`.
 
   4. Contributors discuss **whether the approach of the PR is appropriate** to fix the problem
@@ -52,7 +52,7 @@ this before they became maintainers.
 When will a pull request get reviewed?
 --------------------------------------
 
-When you open a new pull request, :ref:`Area maintainers <doc_areas>` are notified immediately.
+When you open a new pull request, :ref:`area maintainers <doc_areas>` are notified immediately.
 
 However, a lot of pull requests are opened every day, so reviews can take a while to come in. Going by historical data,
 you can expect the following review timelines: