mkdocstrings-github 0.4.2__py3-none-any.whl → 0.6.1__py3-none-any.whl

{mkdocstrings_github-0.4.2.dist-info → mkdocstrings_github-0.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.4.2
+Version: 0.6.1
 Summary: A GitHub Action handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -21,9 +21,9 @@ Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
-Requires-Dist: gitpython~=3.1.45
-Requires-Dist: mkdocstrings~=0.29
-Requires-Dist: packaging~=25.0
+Requires-Dist: gitpython<4,>=3.1.45
+Requires-Dist: mkdocstrings<1,>=0.29
+Requires-Dist: ruamel-yaml<1,>=0.18.16
 Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
 Description-Content-Type: text/markdown
 
@@ -33,14 +33,26 @@ Description-Content-Type: text/markdown
 
 <p align="center">A GitHub Actions handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
 
-<p align="center"><img width=300px src="logo.png"></p>
+<!-- --8<-- [end:header] -->
+
+<p align="center"><img width=300px src="docs/img/logo.png"></p>
 
 [![Qualify](https://github.com/watermarkhu/mkdocstrings-github/actions/workflows/qualify.yaml/badge.svg?branch=main)](https://github.com/watermarkhu/mkdocstrings-github/actions/workflows/qualify.yaml)
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://watermarkhu.nl/mkdocstrings-github)
 [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-github.svg)](https://pypi.org/project/mkdocstrings-github/)
 [![codecov](https://codecov.io/github/watermarkhu/mkdocstrings-github/graph/badge.svg?token=M6XW8UeURE)](https://codecov.io/github/watermarkhu/mkdocstrings-github)
 
-<!-- --8<-- [end:header] -->
+
+
+For example, the following page is generated from [actions/checkout](https://github.com/actions/checkout):
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/example_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="docs/img/example_light.png">
+  <img alt="Fallback image description" src="docs/img/example_light.png">
+</picture>
+
+
 <!-- --8<-- [start:install] -->
 You can install the GitHub handler by specifying it as a dependency:
 
@@ -49,9 +61,17 @@ You can install the GitHub handler by specifying it as a dependency:
 # adapt to your dependencies manager
 [project]
 dependencies = [
-    "mkdocstrings-github>=0.X.Y",
+    "mkdocstrings-github",
 ]
 ```
+
+after which the generated documentation can be inserted in the markdown page with:
+
+```md
+::: <path-to-action-or-workflow>
+    handler: github
+```
+
 <!-- --8<-- [end:install] -->
 
 <!-- --8<-- [start:footer] -->
@@ -63,5 +83,6 @@ dependencies = [
 - 🧩 **Individual Parameter Hyperlinks**: Each action or workflow parameter—including inputs, outputs, and secrets—receives a unique HTML id, facilitating direct linking to specific parameter documentation.
 - 🔒 **Automated Permission Aggregation**: For reusable workflows, if permissions are specified at the job level rather than the workflow level, the required final permissions are automatically determined and displayed in the signature.
 - 🔗 **Parameter cross-linking**: Link to other parameters of the action or workflow via a simple Markdown syntax.
+- 🧑‍🤝‍🧑 **Parameter grouping**: Organize related inputs, outputs, and secrets into visual groups using inline YAML comments for clearer documentation structure.
 
 <!-- --8<-- [end:footer] -->

mkdocstrings_github-0.6.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+mkdocstrings_handlers/github/__init__.py,sha256=0WdFUIq4Xu2ZFtlZNIYCQSoqcx3Ot9Wv41_X_dwbFww,248
+mkdocstrings_handlers/github/config.py,sha256=r7efiI-vKbVEeD6utrc55h4RP6VIlabqDebhiIIx_ZA,7120
+mkdocstrings_handlers/github/handler.py,sha256=SQcd08VA3g4f3Fof2mam85ahPLiK99TteAJJpUg-iB4,8489
+mkdocstrings_handlers/github/objects.py,sha256=v1GchB9fzqasnXbVEOXoDzOR2iVTwcfPQ9mFT4sdjgs,7625
+mkdocstrings_handlers/github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/github/rendering.py,sha256=pFk621Fqp_R6ZS2dJ0zwEEez0Urqpekial6kqKYDag8,3371
+mkdocstrings_handlers/github/templates/material/_macros.html.jinja,sha256=1TNUgoOIxm-a1S7eiESrW1fYuzXOjrwFqXQSyA4tkkU,1576
+mkdocstrings_handlers/github/templates/material/action.html.jinja,sha256=C7S8I9bjnrEUahyDB7CkFxtakFrr53KE3t3uyczBPzc,2864
+mkdocstrings_handlers/github/templates/material/heading.html.jinja,sha256=wnvZpNED8Dhb935qnddeDExXN-MIUz8frRRfgq-A9VA,1396
+mkdocstrings_handlers/github/templates/material/inputs.html.jinja,sha256=UE8RmfMlF6np7CP-920CwgkbXIcKNgl9KgK1BJ588GM,3271
+mkdocstrings_handlers/github/templates/material/outputs.html.jinja,sha256=Z9QD1KSALLDS9VEyugWG1BHpLCHTKYEx4TEQkKIoC3M,2693
+mkdocstrings_handlers/github/templates/material/secrets.html.jinja,sha256=jQ_HaG2ivbZTH74pyV4BAFGQu5Vn03kA_vaEbTSABds,2839
+mkdocstrings_handlers/github/templates/material/style.css,sha256=Nfmds-xHtPJ_IzOv5svA7ih5talHDTiQryN_n0DGdZs,1553
+mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=5dLdHRSQyulyFAVCVZAR_pkw-WXxCtM20cj6RS7IH1Q,4206
+mkdocstrings_github-0.6.1.dist-info/METADATA,sha256=fdZ69Xer6TQ4ZpkPnzyv1P2H2eE5KLi27DltQAJWNqA,4055
+mkdocstrings_github-0.6.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_github-0.6.1.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
+mkdocstrings_github-0.6.1.dist-info/RECORD,,

mkdocstrings_handlers/github/config.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import re
 import sys
 from typing import Literal
 
@@ -92,6 +91,15 @@ class GitHubOptions(BaseModel):
         description="Whether to show the signature in the documentation.",
     )
 
+    signature_repository: str = Field(
+        default="",
+        description="""The GitHub repository in the format *owner/repo*.
+
+        By default, the repository is inferred from the current git repository using the default origin remote.
+        If it cannot be inferred, it must be set manually.
+        """,
+    )
+
     signature_show_secrets: bool = Field(
         default=False,
         description="Whether to show secrets in the signature.",
@@ -162,6 +170,32 @@ class GitHubOptions(BaseModel):
         """,
     )
 
+    parameters_groups: bool = Field(
+        default=True,
+        description="""Whether to group parameters by their group in the documentation.
+
+        This is done by adding a comment `# group: <group name>` directly after the parameter definition in the action/workflow file.
+        This can be done for inputs, outputs and secrets. E.g.:
+
+        ```yaml
+        inputs:
+          my_input: # group: Example Group
+            description: "An example input"
+            required: true
+        ```
+
+        This has no effect if there are no groups defined for any parameter.
+        """,
+    )
+
+    parameters_group_title_row: bool = Field(
+        default=True,
+        description="""Whether to add a title row for each parameter group in the documentation.
+        This only has an effect if [`parameters_groups`][mkdocstrings_handlers.github.config.GitHubOptions.parameters_groups] is set to `true`,
+        and if the [`parameters_section_style`][mkdocstrings_handlers.github.config.GitHubOptions.parameters_section_style] is set to `table`.
+        """,
+    )
+
     parameters_anchors: bool = Field(
         default=True,
         description="Whether to add anchors to parameters in the documentation.",
@@ -171,16 +205,6 @@ class GitHubOptions(BaseModel):
 class GitHubConfig(BaseModel):
     """Configuration options for the GitHub handler."""
 
-    repo: str = Field(
-        default="",
-        description="""The GitHub repository in the format *owner/repo*.
-
-        By default, the repository is inferred from the current git repository using the default origin remote.
-        If it cannot be inferred, it must be set manually.
-        """,
-        pattern=re.compile(r"^[\w.-]+/[\w.-]+$"),
-    )
-
     feather_icons_source: str = Field(
         default="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js",
         description="""The source URL for Feather icons.

mkdocstrings_handlers/github/handler.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import os
 import re
-import sys
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Mapping
 
@@ -68,69 +67,14 @@ class GitHubHandler(BaseHandler):
         self.config = config
         self.repo = repo
         self.global_options = config.options.__dict__
-        self.workflows: dict[Path, Workflow] = {}
-        self.actions: dict[Path, Action] = {}
         self.major: str = ""
         self.semver: str = ""
 
-        # Determine owner and repo name
-        if not self.config.repo:
-            # Try each remote to find a valid GitHub owner/repo
-            owner = None
-            repo_name = None
-            for remote in self.repo.remotes:
-                for url in remote.urls:
-                    match = re.search(
-                        r"(?P<host>[\w\.-]+)[/:](?P<owner>[^/]+)/(?P<repo>[^/.]+?)(?:\.git)?$",
-                        url,
-                    )
-                    if match:
-                        owner = match.group("owner")
-                        repo_name = match.group("repo")
-                        break
-                if owner and repo_name:
-                    break
-            if not (owner and repo_name):
-                raise PluginError(
-                    f"Could not determine GitHub repository owner/name from config.repo='{self.config.repo}' or any git remote URL."
-                )
-            self.config.repo = f"{owner}/{repo_name}"
-
-        # Only run GitHub releases code if required and not in testing
-        not_testing = "pytest" not in sys.modules
-        no_custom_tags = (
-            rendering.ENV_MAJOR_TAG not in os.environ or rendering.ENV_SEMVER_TAG not in os.environ
-        )
-        if not_testing and no_custom_tags:
+        if rendering.ENV_MAJOR_TAG not in os.environ or rendering.ENV_SEMVER_TAG not in os.environ:
             self.get_releases()
 
-        # Glob all workflow YAML files using pathlib
-        working_tree_dir = Path(repo.working_tree_dir)
-        workflows_dir = working_tree_dir / ".github" / "workflows"
-        for workflow_file in list(workflows_dir.glob("*.yml")) + list(workflows_dir.glob("*.yaml")):
-            id = str(workflow_file.relative_to(working_tree_dir))
-            workflow = Workflow.from_file(workflow_file, id)
-            if workflow is not None:
-                self.workflows[workflow_file] = workflow
-
-        # Glob all action.yaml and action.yml files, skipping .git folder entirely using pathlib
-        def find_action_files(base: Path):
-            for entry in base.iterdir():
-                if entry.is_dir():
-                    if entry.name == ".git":
-                        continue
-                    yield from find_action_files(entry)
-                elif entry.is_file() and entry.name in ("action.yaml", "action.yml"):
-                    yield entry
-
-        for action_file in find_action_files(working_tree_dir):
-            id = str(action_file.relative_to(working_tree_dir).parent)
-            action = Action.from_file(action_file, id)
-            if action is not None:
-                self.actions[action_file] = action
-
     def get_releases(self) -> None:
-        # Get all tags from the local git repository
+        # Get all tags from the local git repository.
         try:
             tags = [tag.name for tag in self.repo.tags]
         except Exception as e:
@@ -191,6 +135,34 @@ class GitHubHandler(BaseHandler):
         except Exception as error:
             raise PluginError(f"Invalid options: {error}") from error
 
+    def get_repository_name(self) -> str:
+        # Get repo from environment variable or git remotes.
+        if os.environ.get("GITHUB_ACTIONS") == "true" and (
+            repo := os.environ.get("GITHUB_REPOSITORY")
+        ):
+            return repo
+        else:
+            # Try each remote to find a valid GitHub owner/repo
+            owner = None
+            repo_name = None
+            for remote in self.repo.remotes:
+                for url in remote.urls:
+                    match = re.search(
+                        r"(?P<host>[\w\.-]+)[/:](?P<owner>[^/]+)/(?P<repo>[^/.]+?)(?:\.git)?$",
+                        url,
+                    )
+                    if match:
+                        owner = match.group("owner")
+                        repo_name = match.group("repo")
+                        break
+                if owner and repo_name:
+                    break
+            if not (owner and repo_name):
+                raise PluginError(
+                    "Could not determine GitHub repository owner/name from any git remote URL."
+                )
+            return f"{owner}/{repo_name}"
+
     def update_env(self, config: Any) -> None:
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True
@@ -198,22 +170,34 @@ class GitHubHandler(BaseHandler):
         self.env.filters["format_action_signature"] = rendering.format_action_signature
         self.env.filters["order_parameters"] = rendering.order_parameters
         self.env.filters["filter_parameters"] = rendering.filter_parameters
+        self.env.filters["group_parameters"] = rendering.group_parameters
         self.env.filters["anchor_id"] = rendering.anchor_id
         self.env.filters["as_string"] = rendering.as_string
         self.env.globals["semver_tag"] = self.semver
         self.env.globals["major_tag"] = self.major
         self.env.globals["git_repo"] = self.repo
+        self.env.globals["repository_name"] = self.get_repository_name()
 
-    def collect(self, identifier: str, options: GitHubOptions) -> Workflow | Action:
+    def collect(self, identifier: str, options: GitHubOptions) -> Workflow | Action | None:
         path = Path(self.repo.working_tree_dir) / identifier
-        if path in self.workflows:
-            return self.workflows[path]
-        elif (action_path := path / "action.yml") in self.actions:
-            return self.actions[action_path]
-        elif (action_path := path / "action.yaml") in self.actions:
-            return self.actions[action_path]
+
+        if path.suffix in (".yml", ".yaml"):
+            if not path.is_file():
+                raise CollectionError(f"Identifier '{identifier}' is not a valid workflow file.")
+            data = Workflow.from_file(path, id=identifier)
+        elif not path.is_dir():
+            raise CollectionError(
+                f"Identifier '{identifier}' is not a valid workflow file or action directory."
+            )
+        elif (action_path := path / "action.yml").is_file():
+            data = Action.from_file(action_path, id=identifier)
+        elif (action_path := path / "action.yaml").is_file():
+            data = Action.from_file(action_path, id=identifier)
         else:
-            raise CollectionError(f"Identifier '{identifier}' not found as a workflow or action.")
+            raise CollectionError(
+                f"Identifier '{identifier}' is not a valid workflow file or action directory."
+            )
+        return data
 
     def render(self, data: Workflow | Action, options: GitHubOptions) -> str:
         """Render a template using provided data and configuration options.

mkdocstrings_handlers/github/objects.py

@@ -1,10 +1,28 @@
-from collections import OrderedDict
+import re
 from dataclasses import dataclass, field
 from enum import Enum
 from os import PathLike
 from typing import Any, Literal, Optional
 
-import yaml
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+
+yaml = YAML()
+
+
+GROUP_PATTERN = r"#\s*group:\s*(.+)$"
+
+
+def group_from_map(map: CommentedMap) -> str:
+    """Extract group string from a comment line if it matches the group pattern."""
+    if map.ca.comment:
+        for comment in map.ca.comment:
+            if comment is not None:
+                group_matches = re.finditer(GROUP_PATTERN, comment.value)
+                group_string = next((m.group(1).strip() for m in group_matches), "")
+                if group_string:
+                    return group_string
+    return ""
 
 
 @dataclass
@@ -15,28 +33,15 @@ class Input:
     type: Literal["boolean", "number", "string"] = "string"
     default: bool | float | int | str | None = None
     deprecationMessage: Optional[str] = None
-
-    @staticmethod
-    def from_data(
-        name: str,
-        description: str = "",
-        required: bool = False,
-        type: Literal["boolean", "number", "string"] = "string",
-        default: bool | float | int | str | None = None,
-        deprecationMessage: Optional[str] = None,
-        **kwargs,
-    ) -> "Input":
-        return Input(name, description, required, type, default, deprecationMessage)
+    group: str = ""
 
 
 @dataclass
 class Output:
     name: str
     description: str = ""
-
-    @staticmethod
-    def from_data(name: str, description: str = "", **kwargs) -> "Output":
-        return Output(name, description)
+    value: str = ""
+    group: str = ""
 
 
 @dataclass
@@ -44,10 +49,7 @@ class Secret:
     name: str
     description: str = ""
     required: bool = False
-
-    @staticmethod
-    def from_data(name: str, description: str = "", required: bool = False, **kwargs) -> "Secret":
-        return Secret(name, description, required)
+    group: str = ""
 
 
 def _get_member(d: dict, key: str, error_message: str = "", default: Any = None) -> Any:
@@ -58,36 +60,11 @@ def _get_member(d: dict, key: str, error_message: str = "", default: Any = None)
     return d[key]
 
 
-class _OrderedLoader(yaml.Loader):
-    pass
-
-
-# Remove boolean resolver for "on", "off", "yes", "no" (and case variants)
-for ch in "yYnNoO":
-    if ch in _OrderedLoader.yaml_implicit_resolvers:
-        _OrderedLoader.yaml_implicit_resolvers[ch] = [
-            res
-            for res in _OrderedLoader.yaml_implicit_resolvers[ch]
-            if res[0] != "tag:yaml.org,2002:bool"
-        ]
-
-
-def _construct_mapping(loader, node):
-    loader.flatten_mapping(node)
-    return OrderedDict(loader.construct_pairs(node))
-
-
-_OrderedLoader.add_constructor(
-    yaml.SafeLoader.DEFAULT_MAPPING_TAG,
-    _construct_mapping,
-)
-
-
 def _read_file(file: PathLike) -> tuple[str, dict]:
     with open(file, "r", encoding="utf-8") as f:
         source = f.read()
         f.seek(0)
-        data = yaml.load(f, Loader=_OrderedLoader)
+        data = yaml.load(f)
     return source, data
 
 
@@ -106,10 +83,6 @@ class Action:
     branding: dict = field(default_factory=dict)
     template: Literal["action.html.jinja"] = "action.html.jinja"
 
-    @property
-    def members(self) -> list[Input | Output]:
-        return self.inputs + self.outputs
-
     @staticmethod
     def from_file(file: PathLike, id: str) -> "Action":
         source, data = _read_file(file)
@@ -125,12 +98,31 @@ class Action:
             branding=_get_member(data, "branding", default={}),
         )
         for key, value in data.get("inputs", {}).items():
-            action.inputs.append(Input.from_data(key, **value))
+            action.inputs.append(Input(name=key, **value, group=group_from_map(value)))
         for key, value in data.get("outputs", {}).items():
-            action.outputs.append(Output.from_data(key, **value))
+            action.outputs.append(Output(name=key, **value, group=group_from_map(value)))
         return action
 
 
+# https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions
+PERMISSION_SCOPES: list[str] = [
+    "actions",
+    "attestations",
+    "checks",
+    "contents",
+    "deployments",
+    "discussions",
+    "id-token",
+    "issues",
+    "models",
+    "packages",
+    "pages",
+    "pull-requests",
+    "security-events",
+    "statuses",
+]
+
+
 class PermissionLevel(Enum):
     none = ("none", 0)
     read = ("read", 1)
@@ -151,21 +143,6 @@ class PermissionLevel(Enum):
                 return perm
         raise ValueError(f"No Permission with label '{label}'")
 
-    def __le__(self, other):
-        if isinstance(other, PermissionLevel):
-            return self.number <= other.number
-        return NotImplemented
-
-    def __lt__(self, other):
-        if isinstance(other, PermissionLevel):
-            return self.number < other.number
-        return NotImplemented
-
-    def __ge__(self, other):
-        if isinstance(other, PermissionLevel):
-            return self.number >= other.number
-        return NotImplemented
-
     def __gt__(self, other):
         if isinstance(other, PermissionLevel):
             return self.number > other.number
@@ -187,8 +164,18 @@ class Workflow:
     template: Literal["workflow.html.jinja"] = "workflow.html.jinja"
 
     @property
-    def members(self) -> list[Input | Output | Secret]:
-        return self.inputs + self.outputs + self.secrets
+    def permission_read_all(self) -> bool:
+        return all(
+            scope in self.permissions and self.permissions[scope] == PermissionLevel.read
+            for scope in PERMISSION_SCOPES
+        )
+
+    @property
+    def permission_write_all(self) -> bool:
+        return all(
+            scope in self.permissions and self.permissions[scope] == PermissionLevel.write
+            for scope in PERMISSION_SCOPES
+        )
 
     @staticmethod
     def from_file(file: PathLike, id: str) -> "Workflow | None":
@@ -208,18 +195,41 @@ class Workflow:
         call = data["on"]["workflow_call"]
         if call:
             for key, value in call.get("inputs", {}).items():
-                workflow.inputs.append(Input.from_data(key, **value))
+                workflow.inputs.append(Input(name=key, **value, group=group_from_map(value)))
             for key, value in call.get("outputs", {}).items():
-                workflow.outputs.append(Output.from_data(key, **value))
+                workflow.outputs.append(Output(name=key, **value, group=group_from_map(value)))
             for key, value in call.get("secrets", {}).items():
-                workflow.secrets.append(Secret.from_data(key, **value))
-        for key, label in data.get("permissions", {}).items():
-            workflow.permissions[key] = PermissionLevel.from_label(label)
+                workflow.secrets.append(Secret(name=key, **value, group=group_from_map(value)))
+
+        def set_all_permissions(level: str):
+            if level == "read-all":
+                for key in PERMISSION_SCOPES:
+                    workflow.permissions[key] = PermissionLevel.read
+            elif level == "write-all":
+                for key in PERMISSION_SCOPES:
+                    workflow.permissions[key] = PermissionLevel.write
+            else:
+                raise ValueError(f"Unknown permission level '{level}'")
+
+        if isinstance(permissions := data.get("permissions", {}), str):
+            set_all_permissions(permissions)
+        elif isinstance(permissions, dict):
+            for key, label in permissions.items():
+                workflow.permissions[key] = PermissionLevel.from_label(label)
+        else:
+            raise ValueError("permissions must be a string or a dictionary")
         for job in data.get("jobs", {}).values():
-            for key, label in job.get("permissions", {}).items():
-                if key in workflow.permissions:
-                    if permission := PermissionLevel.from_label(label) > workflow.permissions[key]:
-                        workflow.permissions[key] = permission
-                else:
-                    workflow.permissions[key] = PermissionLevel.from_label(label)
+            if isinstance(permissions := job.get("permissions", {}), str):
+                set_all_permissions(permissions)
+            elif isinstance(permissions, dict):
+                for key, label in job.get("permissions", {}).items():
+                    if key in workflow.permissions:
+                        permission = PermissionLevel.from_label(label)
+                        if permission > workflow.permissions[key]:
+                            workflow.permissions[key] = permission
+                    else:
+                        workflow.permissions[key] = PermissionLevel.from_label(label)
+            else:
+                raise ValueError("permissions must be a string or a dictionary")
+
         return workflow

mkdocstrings_handlers/github/rendering.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+from collections import OrderedDict
 from typing import TYPE_CHECKING, Sequence
 
 from jinja2 import pass_context
@@ -23,8 +24,11 @@ def format_action_signature(context: Context, id: str, repo: str, options: GitHu
     match options.signature_version:
         case "ref":
             try:
-                repo: Repo = context.environment.globals["git_repo"]
-                version = repo.head.ref.name
+                git_repo = context.environment.globals["git_repo"]
+                if isinstance(git_repo, Repo):
+                    version = git_repo.head.ref.name
+                else:
+                    version = "unknown"
             except Exception:
                 version = "unknown"
         case "major":
@@ -37,6 +41,22 @@ def format_action_signature(context: Context, id: str, repo: str, options: GitHu
     return f"{name}@{version}"
 
 
+def group_parameters(
+    parameters: Sequence[Input | Output | Secret],
+    do_group: bool,
+) -> OrderedDict[str, list[Input | Output | Secret]]:
+    grouped: OrderedDict[str, list[Input | Output | Secret]] = OrderedDict()
+    if not do_group:
+        grouped[""] = list(parameters)
+        return grouped
+    for parameter in parameters:
+        group = getattr(parameter, "group", "")
+        if group not in grouped:
+            grouped[group] = []
+        grouped[group].append(parameter)
+    return grouped
+
+
 def order_parameters(
     parameters: Sequence[Input | Output | Secret], parameters_order: PARAMETERS_ORDER
 ):

mkdocstrings_handlers/github/templates/material/_macros.html.jinja

@@ -0,0 +1,38 @@
+{#- Shared macros for rendering parameters in different styles -#}
+
+{#- Macro to render a single parameter item in list style -#}
+{% macro render_parameter_item(item, item_type, options, data) %}
+  {% set anchor_id = item.name | anchor_id(item_type, data.id) %}
+  <li class="doc-section-item field-body">
+    <b><code>{{ item.name }}</code></b>
+    {%- if item.required is defined and item.required %} - <em>required</em>{% endif %}
+    {% if options.parameters_anchors %}
+      <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ item.name }}">¤</a>
+    {% endif %}
+    <div class="doc-md-description">
+      {{ item.description | convert_markdown(options.heading_level, data.id) }}
+    </div>
+    {% if item.default is defined and item.default is not none %}
+      <div class="doc-md-description">
+        <code>{{ item.default | as_string }}</code>
+      </div>
+    {% endif %}
+  </li>
+{% endmacro %}
+
+{#- Macro to render grouped parameters in list style -#}
+{% macro render_grouped_list(items, item_type, options, data) %}
+  {% set grouped_items = items | group_parameters(options.parameters_groups) %}
+  {% for group, group_items in grouped_items.items() %}
+    {% if group %}
+      <li class="gh-group-item">
+        <em>{{ group }}:</em>
+        <ul>
+          {% for item in group_items %}{{ render_parameter_item(item, item_type, options, data) }}{% endfor %}
+        </ul>
+      </li>
+    {% else %}
+      {% for item in group_items %}{{ render_parameter_item(item, item_type, options, data) }}{% endfor %}
+    {% endif %}
+  {% endfor %}
+{% endmacro %}

mkdocstrings_handlers/github/templates/material/action.html.jinja

@@ -7,7 +7,6 @@ Context:
   config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
   options (dict): The local options
 -#}
-
 {% block logs scoped %}
   {#- Logging block.
 
@@ -23,20 +22,30 @@ Context:
 
   {% include "heading.html.jinja" with context %}
 
-  {% set signature = data.id | format_action_signature(config.repo, options) %}
+  {% set signature = data.id | format_action_signature(options.signature_repository if options.signature_repository else repository_name, options) %}
 
   {% block signature scoped %}
     {% if options.show_signature %}
       {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+        <div class="annotate">
         {% filter highlight(language="yaml", inline=False, linenums=False) %}
           - uses: {{ signature }}
+          {% if inputs|length > 0 %}
             with:
-              {%+ for input in inputs %}{{ input.name }}: ''{% endfor +%}
+              {% for input in inputs %}
+              {{ input.name }}: ({{ loop.index }})
+              {% endfor %}
+          {% endif %}
         {% endfilter %}
+        </div>
+        <ol>
+        {% for input in inputs %}
+          <li>{{ input.description | convert_markdown(options.heading_level) if input.description else "(no description)" }}</li>
+        {% endfor %}
+        </ol>
       {% endwith %}
     {% endif %}
   {% endblock signature %}
-
   {% block description scoped %}
     {% if options.show_description %}
       {{ options.description if options.description else data.description | convert_markdown(options.heading_level, data.id) }}

mkdocstrings_handlers/github/templates/material/inputs.html.jinja

@@ -7,6 +7,8 @@ Context:
   options (dict): The local options
 -#}
 
+{% from "_macros.html.jinja" import render_grouped_list %}
+
 {% block logs scoped %}
   {{ log.debug("Rendering inputs of " + data.id) }}
 {% endblock logs %}
@@ -27,7 +29,7 @@ Context:
       <span class="doc-section-title">Inputs:</span>
       <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
     </p>
-    <table>
+    <table data-gh-parameters>
       <thead>
         <tr>
           <th>Name</th>
@@ -35,8 +37,15 @@ Context:
           {% if default_column %}<th>Default</th>{% endif %}
         </tr>
       </thead>
+      {% set grouped_inputs = inputs | group_parameters(options.parameters_groups) %}
+      {% for group, group_inputs in grouped_inputs.items() %}
       <tbody>
-        {% for input in inputs %}
+        {% if options.parameters_group_title_row and grouped_inputs | length > 1 and group != "" %}
+        <tr class="doc-section-item">
+          <td class="gh-group-title" colspan="{% if default_column %}3{% else %}2{% endif %}">{{ group }}</td>
+        </tr>
+        {% endif %}
+        {% for input in group_inputs %}
           {% if options.parameters_anchors %}
             {% set anchor_id = input.name | anchor_id("inputs", data.id) %}
           {% else %}
@@ -66,6 +75,7 @@ Context:
           </tr>
         {% endfor %}
       </tbody>
+      {% endfor %}
     </table>
   {% endblock table_style %}
 {% elif options.parameters_section_style == "list" %}
@@ -75,24 +85,7 @@ Context:
       <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
     </p>
     <ul>
-      {% for input in inputs %}
-        {% set anchor_id = input.name | anchor_id("inputs", data.id) %}
-        <li class="doc-section-item field-body">
-          <b><code>{{ input.name }}</code></b>
-          {%- if input.required %} - <em>required</em>{% endif %}
-          {% if options.parameters_anchors %}
-            <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ input.name }}">¤</a>
-          {% endif %}
-          <div class="doc-md-description">
-            {{ input.description | convert_markdown(options.heading_level, data.id) }}
-          </div>
-          {% if input.default is not none %}
-            <div class="doc-md-description">
-              Default: <code>{{ input.default | as_string }}</code>
-            </div>
-          {% endif %}
-        </li>
-      {% endfor %}
+      {{ render_grouped_list(inputs, "inputs", options, data) }}
     </ul>
   {% endblock list_style %}
 {% endif %}

mkdocstrings_handlers/github/templates/material/outputs.html.jinja

@@ -7,6 +7,8 @@ Context:
   options (dict): The local options
 -#}
 
+{% from "_macros.html.jinja" import render_grouped_list %}
+
 {% block logs scoped %}
   {{ log.debug("Rendering outputs of " + data.id) }}
 {% endblock logs %}
@@ -24,15 +26,22 @@ Context:
       <span class="doc-section-title">Outputs:</span>
       <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
     </p>
-    <table>
+    <table data-gh-parameters>
       <thead>
         <tr>
           <th>Name</th>
           <th>Description</th>
         </tr>
       </thead>
+      {% set grouped_outputs = outputs | group_parameters(options.parameters_groups) %}
+      {% for group, group_outputs in grouped_outputs.items() %}
       <tbody>
-        {% for output in outputs %}
+        {% if options.parameters_group_title_row and grouped_outputs | length > 1 and group != "" %}
+        <tr class="doc-section-item">
+          <td class="gh-group-title" colspan="2">{{ group }}</td>
+        </tr>
+        {% endif %}
+        {% for output in group_outputs %}
           {% if options.parameters_anchors %}
             {% set anchor_id = output.name | anchor_id("outputs", data.id) %}
           {% else %}
@@ -48,8 +57,10 @@ Context:
             <td>
               {{ output.description | convert_markdown(options.heading_level, data.id) }}
             </td>
+          </tr>
         {% endfor %}
       </tbody>
+      {% endfor %}
     </table>
   {% endblock table_style %}
 {% elif options.parameters_section_style == "list" %}
@@ -59,18 +70,7 @@ Context:
       <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
     </p>
     <ul>
-      {% for output in outputs %}
-        {% set anchor_id = output.name | anchor_id("outputs", data.id) %}
-        <li class="doc-section-item field-body">
-          <b><code>{{ output.name }}</code></b>
-          {% if options.parameters_anchors %}
-            <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ output.name }}">¤</a>
-          {% endif %}
-          <div class="doc-md-description">
-              {{ output.description | convert_markdown(options.heading_level, data.id) }}
-          </div>
-        </li>
-      {% endfor %}
+      {{ render_grouped_list(outputs, "outputs", options, data) }}
     </ul>
   {% endblock list_style %}
 {% endif %}

mkdocstrings_handlers/github/templates/material/secrets.html.jinja

@@ -7,6 +7,8 @@ Context:
   options (dict): The local options
 -#}
 
+{% from "_macros.html.jinja" import render_grouped_list %}
+
 {% block logs scoped %}
   {{ log.debug("Rendering secrets of " + data.id) }}
 {% endblock logs %}
@@ -24,15 +26,22 @@ Context:
       <span class="doc-section-title">Secrets:</span>
       <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
     </p>
-    <table>
+    <table data-gh-parameters>
       <thead>
         <tr>
           <th>Name</th>
           <th>Description</th>
         </tr>
       </thead>
+      {% set grouped_secrets = secrets | group_parameters(options.parameters_groups) %}
+      {% for group, group_secrets in grouped_secrets.items() %}
       <tbody>
-        {% for secret in secrets %}
+        {% if options.parameters_group_title_row and grouped_secrets | length > 1 and group != "" %}
+        <tr class="doc-section-item">
+          <td class="gh-group-title" colspan="2">{{ group }}</td>
+        </tr>
+        {% endif %}
+        {% for secret in group_secrets %}
           {% if options.parameters_anchors %}
             {% set anchor_id = secret.name | anchor_id("secrets", data.id) %}
           {% else %}
@@ -52,8 +61,10 @@ Context:
             <td>
               {{ secret.description | convert_markdown(options.heading_level, data.id) }}
             </td>
+          </tr>
         {% endfor %}
       </tbody>
+      {% endfor %}
     </table>
   {% endblock table_style %}
 {% elif options.parameters_section_style == "list" %}
@@ -63,19 +74,7 @@ Context:
       <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
     </p>
     <ul>
-      {% for secret in secrets %}
-        {% set anchor_id = secret.name | anchor_id("secrets", data.id) %}
-        <li class="doc-section-item field-body">
-          <b><code>{{ secret.name }}</code></b>
-          {%- if secret.required %} - <em>required</em>{% endif %}
-          {% if options.parameters_anchors %}
-            <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ secret.name }}">¤</a>
-          {% endif %}
-          <div class="doc-md-description">
-            {{ secret.description | convert_markdown(options.heading_level, data.id) }}
-          </div>
-        </li>
-      {% endfor %}
+      {{ render_grouped_list(secrets, "secrets", options, data) }}
     </ul>
   {% endblock list_style %}
 {% endif %}

mkdocstrings_handlers/github/templates/material/style.css

@@ -57,3 +57,22 @@
   background-color: #24292e;
   color: #ffffff;
 }
+
+
+/* Add thicker divider between thead and tbody, and between tbody groups */
+table[data-gh-parameters] thead + tbody tr:first-child td,
+table[data-gh-parameters] tbody:not(:first-of-type) tr:first-child td {
+  border-top: 2px solid var(--md-default-fg-color--lighter) !important;
+}
+
+/* Disable word-wrap in first column (except group titles) */
+table[data-gh-parameters] td:first-child:not(.gh-group-title) {
+  white-space: nowrap;
+}
+
+/* Style group title rows */
+table[data-gh-parameters] td.gh-group-title {
+  text-align: center !important;
+  font-style: italic;
+  white-space: normal;
+}

mkdocstrings_handlers/github/templates/material/workflow.html.jinja

@@ -20,28 +20,50 @@ Context:
 <div class="doc doc-object doc-workflow">
   {% include "heading.html.jinja" with context %}
 
-  {% set signature = data.id | format_action_signature(config.repo, options) %}
+  {% set signature = data.id | format_action_signature(options.signature_repository if options.signature_repository else repository_name, options) %}
 
   {% block signature scoped %}
     {% if options.show_signature %}
-      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True), secrets = data.secrets | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+        <div class="annotate">
         {% filter highlight(language="yaml", inline=False, linenums=False) %}
           uses: {{ signature }}
-          {% if options.signature_show_permissions and data.permissions %}
+          {% if options.signature_show_permissions and data.permissions|length > 0 %}
+          {% if data.permission_read_all %}
+          permissions: read-all
+          {% elif data.permission_write_all %}
+          permissions: write-all
+          {% else %}
           permissions:
             {% for scope, level in data.permissions | items %}
             {{ scope }}: {{ level.label }}
             {% endfor %}
           {% endif %}
+          {% endif %}
+          {% if inputs|length > 0 %}
           with:
-            {%+ for input in inputs %}{{ input.name }}: ''{% endfor +%}
+            {% for input in inputs %}
+            {{ input.name }}: ({{ loop.index }})
+            {% endfor %}
+          {% endif %}
           {% if options.signature_show_secrets %}
-            {% with secrets = data.secrets | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+          {% if secrets|length > 0 %}
           secrets:
-            {%+ for secret in secrets %}{{ secret.name }}: ''{% endfor +%}
-            {% endwith %}
+            {% for secret in secrets %}
+            {{ secret.name }}: ({{ inputs|length + loop.index }})
+            {% endfor %}
+          {% endif %}
           {% endif %}
         {% endfilter %}
+        </div>
+        <ol>
+        {% for input in inputs %}
+          <li>{{ input.description | convert_markdown(options.heading_level) if input.description else "(no description)" }}</li>
+        {% endfor %}
+        {% for secret in secrets %}
+          <li>{{ secret.description | convert_markdown(options.heading_level) if secret.description else "(no description)" }}</li>
+        {% endfor %}
+        </ol>
       {% endwith %}
     {% endif %}
   {% endblock signature %}

mkdocstrings_github-0.4.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-mkdocstrings_handlers/github/__init__.py,sha256=0WdFUIq4Xu2ZFtlZNIYCQSoqcx3Ot9Wv41_X_dwbFww,248
-mkdocstrings_handlers/github/config.py,sha256=pSjA6gU-kC_mXQqNIIGOYEOhtX5VzZDT0H1hRFlGaj8,6089
-mkdocstrings_handlers/github/handler.py,sha256=d3bpciheO6BSH1EPAc8ijZ_xmcEzzhXTbfTrbcMmFIg,9310
-mkdocstrings_handlers/github/objects.py,sha256=JDkY7mg_LGlIEwZHP2wSd8ZkB6RVtRsu_JEpwV-PikQ,7069
-mkdocstrings_handlers/github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/github/rendering.py,sha256=tJeAsSaijqSC2IkxYsIXq7d0lR2A3aB5PRUcFFTFpVU,2705
-mkdocstrings_handlers/github/templates/material/action.html.jinja,sha256=87NCgz-zY16rU7tEmJETJ0gLwdzxoBrqLtp9vsVCsiw,2435
-mkdocstrings_handlers/github/templates/material/heading.html.jinja,sha256=wnvZpNED8Dhb935qnddeDExXN-MIUz8frRRfgq-A9VA,1396
-mkdocstrings_handlers/github/templates/material/inputs.html.jinja,sha256=CIcw3OBQdCP4e5A4srLu1v3xoOjsedIw1Zh3qxtG0-A,3482
-mkdocstrings_handlers/github/templates/material/outputs.html.jinja,sha256=jlzVF93q5AyJfOiSl3_1VBVL3c6rjmEcS81s3sri5Gg,2670
-mkdocstrings_handlers/github/templates/material/secrets.html.jinja,sha256=1lMJoxjjeiqetVu0mdLKmZ1faYRReeyjiYvYTZESots,2881
-mkdocstrings_handlers/github/templates/material/style.css,sha256=R2hh1RfHwJ6XNT4YQl_txNkNXcPBZJMCBZn5kQEMQ6M,962
-mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=E1VUi2w7_NDkpS9VNrWRV52hhyhQvnKUrjPbV_j0Qcg,3312
-mkdocstrings_github-0.4.2.dist-info/METADATA,sha256=humw71gGT_wkykxy7fRgxh_t1ri6JOm3keuIkoiGIyU,3340
-mkdocstrings_github-0.4.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mkdocstrings_github-0.4.2.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
-mkdocstrings_github-0.4.2.dist-info/RECORD,,