mkdocstrings-github 0.1.0__py3-none-any.whl

mkdocstrings_github-0.1.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: mkdocstrings-github
+Version: 0.1.0
+Summary: A GitHub Action handler for mkdocstrings
+Author-email: Mark Hu <watermarkhu@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Requires-Dist: gitpython~=3.1.45
+Requires-Dist: mkdocstrings~=0.29
+Requires-Dist: pygithub~=2.8.1
+Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+<!-- --8<-- [start:header] -->
+
+<h1 align="center">mkdocstrings-github</h1>
+
+<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>
+
+[![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/)
+
+<!-- --8<-- [end:header] -->
+<!-- --8<-- [start:install] -->
+You can install the GitHub handler by specifying it as a dependency:
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+    "mkdocstrings-github>=0.X.Y",
+]
+```
+<!-- --8<-- [end:install] -->
+
+<!-- --8<-- [start:footer] -->
+
+## Features
+
+- 📝 **Automatic Example Signature**: Displays an example call signature alongside the description. The version shown can be the latest release, latest major, current reference, or any custom string.
+- ✨ **Enhanced Markdown Descriptions**: All description elements are parsed using a markdown parser, enabling comprehensive formatting and rich documentation capabilities.
+- 🧩 **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.
+
+<!-- --8<-- [end:footer] -->

mkdocstrings_github-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+mkdocstrings_handlers/github/__init__.py,sha256=0WdFUIq4Xu2ZFtlZNIYCQSoqcx3Ot9Wv41_X_dwbFww,248
+mkdocstrings_handlers/github/config.py,sha256=Lma2xz46TfG5Tgj-Bkh6Lqa1hBuJH3uCtmfOFab7kI4,5459
+mkdocstrings_handlers/github/handler.py,sha256=dN3maFhASZc4JzJKjpgMTDeXuz9VBwjR2YygnvTIEdk,8017
+mkdocstrings_handlers/github/objects.py,sha256=deZlW1nuyaFd4FivOA5dJb2uzY7gHTheTdUzMkOIS9E,6796
+mkdocstrings_handlers/github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/github/rendering.py,sha256=XxejVRXR8n5pkKHAPyYWx4n0NyH8kHNUy2uHRlhQA3w,2184
+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=zP7z_9CO248LhSwvQZ-eG54y73DB67M2TFwNI5iFfM4,3352
+mkdocstrings_handlers/github/templates/material/outputs.html.jinja,sha256=zDmKj9QjD9kd3VVN3xZqQSncVdNjXnTs1m98_Hj2hTM,2780
+mkdocstrings_handlers/github/templates/material/secrets.html.jinja,sha256=uaKsGH_08JSdy5WbjDiDNaYaOXkCJ1K6Ac-6wYkLo2c,2990
+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.1.0.dist-info/METADATA,sha256=4zfACSDnMmVa33t2ZLF8OFa7Cx4r-MRZvsYb9wTICUc,3008
+mkdocstrings_github-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_github-0.1.0.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
+mkdocstrings_github-0.1.0.dist-info/RECORD,,

mkdocstrings_github-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mkdocstrings_github-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mark Shui Hu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocstrings_handlers/github/__init__.py

@@ -0,0 +1,9 @@
+from mkdocstrings_handlers.github.config import GitHubConfig, GitHubOptions
+from mkdocstrings_handlers.github.handler import GitHubHandler, get_handler
+
+__all__ = [
+    "GitHubHandler",
+    "GitHubConfig",
+    "GitHubOptions",
+    "get_handler",
+]

mkdocstrings_handlers/github/config.py

@@ -0,0 +1,189 @@
+"""Configuration and options dataclasses."""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Literal
+
+from mkdocstrings import get_logger
+from pydantic import BaseModel, Field
+
+# YORE: EOL 3.10: Replace block with line 2.
+if sys.version_info >= (3, 11):
+    pass
+else:
+    pass
+
+
+logger = get_logger(__name__)
+
+
+SIGNATURE_VERSION = Literal["ref", "major", "semver", "string"]
+PARAMETERS_ORDER = Literal["alphabetical", "source"]
+PARAMETERS_SECTION_STYLE = Literal["table", "list"]
+
+
+class GitHubOptions(BaseModel):
+    """Input options for the GitHub handler."""
+
+    # General options
+    show_description: bool = Field(
+        default=True,
+        description="Whether to show the description in the documentation.",
+    )
+
+    description: str = Field(
+        default="",
+        description="A custom string to override the autogenerated description of the object.",
+    )
+
+    show_source: bool = Field(
+        default=True,
+        description="Whether to show the source link in the documentation.",
+    )
+
+    # Heading options
+    show_heading: bool = Field(
+        default=True,
+        description="Whether to show the heading in the documentation.",
+    )
+
+    heading: str = Field(
+        default="",
+        description="A custom string to override the autogenerated heading of the object.",
+    )
+
+    heading_level: int = Field(
+        default=2,
+        description="The initial heading level to use.",
+    )
+
+    show_branding: bool = Field(
+        default=True,
+        description="Whether to show the action branding (logo and color) in the documentation.",
+    )
+
+    branding_icon: str = Field(
+        default="",
+        description="Custom icon from https://feathericons.com/ to use for the branding.",
+    )
+
+    branding_icon_color: str = Field(
+        default="",
+        description="Custom icon color for the feather icon.",
+    )
+
+    show_toc_entry: bool = Field(
+        default=True,
+        description="If the heading is not shown, at least add a ToC entry for it.",
+    )
+
+    toc_label: str = Field(
+        default="",
+        description="A custom string to override the autogenerated toc label of the root object.",
+    )
+
+    # Signature options
+    show_signature: bool = Field(
+        default=True,
+        description="Whether to show the signature in the documentation.",
+    )
+
+    signature_show_secrets: bool = Field(
+        default=False,
+        description="Whether to show secrets in the signature.",
+    )
+
+    signature_show_permissions: bool = Field(
+        default=True,
+        description="Whether to show permissions in the workflow signature.",
+    )
+
+    signature_version: SIGNATURE_VERSION = Field(
+        default="ref",
+        description="The versioning scheme to use for the signature.",
+    )
+
+    signature_version_string: str = Field(
+        default="latest",
+        description="The version string to use if `signature_version` is set to `string`.",
+    )
+
+    # Parameter options
+    show_inputs: bool = Field(
+        default=True,
+        description="Whether to show inputs in the documentation.",
+    )
+
+    show_inputs_only_required: bool = Field(
+        default=False,
+        description="Whether to show only required inputs in the documentation.",
+    )
+
+    show_outputs: bool = Field(
+        default=False,
+        description="Whether to show outputs in the documentation.",
+    )
+
+    show_secrets: bool = Field(
+        default=True,
+        description="Whether to show secrets in the documentation.",
+    )
+
+    show_secrets_only_required: bool = Field(
+        default=False,
+        description="Whether to show only required secrets in the documentation.",
+    )
+
+    parameters_order: PARAMETERS_ORDER = Field(
+        default="source",
+        description="""The parameters ordering to use.
+
+        - `alphabetical`: order by the parameters names,
+        - `source`: order parameters as they appear in the source file.
+        """,
+    )
+
+    parameters_section_style: PARAMETERS_SECTION_STYLE = Field(
+        default="table",
+        description="""The style used to render docstring sections.
+
+        - `table`: render parameters in a table,
+        - `list`: render parameters in a list.
+        """,
+    )
+
+    parameters_anchors: bool = Field(
+        default=True,
+        description="Whether to add anchors to parameters in the documentation.",
+    )
+
+
+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.
+
+        In certain enterprise environments, external CDN access may be restricted.
+        In such cases, you can host the `feather.min.js` file locally and set this option to the local path or URL.
+        See more information at https://github.com/feathericons/feather.
+        """,
+    )
+
+    options: GitHubOptions = Field(
+        default_factory=GitHubOptions,
+        description="Options for the GitHub handler.",
+    )

mkdocstrings_handlers/github/handler.py

@@ -0,0 +1,214 @@
+"""The mkdocstrings handler for processing MATLAB code documentation."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar, Mapping
+
+import git
+from mkdocs.exceptions import PluginError
+from mkdocstrings import (
+    BaseHandler,
+    CollectionError,
+    HandlerOptions,
+    get_logger,
+)
+
+from github import Github
+from mkdocstrings_handlers.github import rendering
+from mkdocstrings_handlers.github.config import GitHubConfig, GitHubOptions
+from mkdocstrings_handlers.github.objects import Action, Workflow
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    from mkdocs.config.defaults import MkDocsConfig
+
+
+SEMVER_PATTERN = re.compile(r"^v(\d+\.\d+\.\d+)$")
+MAJOR_PATTERN = re.compile(r"^v(\d+)$")
+
+
+_logger = get_logger(__name__)
+
+
+class GitHubHandler(BaseHandler):
+    """The `GitHubHandler` class is a handler for processing GitHub code documentation."""
+
+    name: ClassVar[str] = "github"
+    """The GitHub handler class."""
+
+    domain: ClassVar[str] = "gh"  # to match Sphinx's default domain
+    """The cross-documentation domain/language for this handler."""
+
+    enable_inventory: ClassVar[bool] = True
+    """Whether this handler is interested in enabling the creation of the `objects.inv` Sphinx inventory file."""
+
+    fallback_theme: ClassVar[str] = "material"
+    """The fallback theme."""
+
+    def __init__(
+        self,
+        config: GitHubConfig,
+        repo: git.Repo,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the handler with the given configuration.
+
+        Args:
+            config: The handler configuration.
+            base_dir: The base directory of the project.
+            **kwargs: Arguments passed to the parent constructor.
+        """
+        super().__init__(**kwargs)
+        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 = ""
+
+        # Only run GitHub releases code if not running under pytest
+        if (
+            rendering.ENV_MAJOR_TAG not in os.environ or rendering.ENV_SEMVER_TAG not in os.environ
+        ) and "pytest" not in sys.modules:
+            # Use PyGitHub to find last GitHub releases with tags matching vX.X.X and vX
+            gh = Github()
+            owner, repo_name = self.config.repo.split("/", 1)
+            gh_repo = gh.get_repo(f"{owner}/{repo_name}")
+            releases = list(gh_repo.get_releases())
+            for release in releases:
+                tag = release.tag_name
+                if not self.semver and SEMVER_PATTERN.match(tag):
+                    self.semver = tag
+                if not self.major and MAJOR_PATTERN.match(tag):
+                    self.major = tag
+                if self.semver and self.major:
+                    break
+            else:
+                _logger.warning(
+                    "Could not find suitable GitHub releases for repo '%s'. "
+                    "Make sure there are releases with tags matching 'vX.X.X' and 'vX', "
+                    "if you wish to use the 'semver' and 'major' signature versions.",
+                    self.config.repo,
+                )
+
+        if self.config.repo == ".":
+            url = next(repo.remote("origin").urls)
+            match = re.search(r"github.com[:/](?P<owner>[^/]+)/(?P<repo>[^/.]+)", url)
+            if match:
+                self.config.repo = f"{match.group('owner')}/{match.group('repo')}"
+            else:
+                _logger.warning(
+                    "Could not determine GitHub repository automatically from git remote URL '%s'. "
+                    "Make sure the remote URL is a GitHub URL, "
+                    "or set the 'repo' option in the configuration.",
+                    url,
+                )
+
+        # 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_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
+        """Get combined default, global and local options.
+
+        Arguments:
+            local_options: The local options.
+
+        Returns:
+            The combined options.
+        """
+
+        options = {**self.global_options, **local_options}
+        try:
+            return GitHubOptions(**options)
+        except Exception as error:
+            raise PluginError(f"Invalid options: {error}") from error
+
+    def update_env(self, config: Any) -> None:
+        self.env.trim_blocks = True
+        self.env.lstrip_blocks = True
+        self.env.keep_trailing_newline = False
+        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.globals["semver_tag"] = self.semver
+        self.env.globals["major_tag"] = self.major
+        self.env.globals["git_repo"] = self.repo
+
+    def collect(self, identifier: str, options: GitHubOptions) -> Workflow | Action:
+        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]
+        else:
+            raise CollectionError(f"Identifier '{identifier}' not found as a workflow or action.")
+
+    def render(self, data: Workflow | Action, options: GitHubOptions) -> str:
+        """Render a template using provided data and configuration options.
+
+        Arguments:
+            data: The collected data to render.
+            options: The handler's configuration options.
+
+        Returns:
+            The rendered template as HTML.
+        """
+        template = self.env.get_template(data.template)
+        html = template.render(options=options, data=data, config=self.config)
+        return html
+
+
+def get_handler(
+    handler_config: MutableMapping[str, Any],
+    tool_config: MkDocsConfig,
+    **kwargs: Any,
+) -> GitHubHandler:
+    """
+    Create and return a GitHubHandler object with the specified configuration.
+
+    Parameters:
+        handler_config: The handler configuration.
+        tool_config: The tool (SSG) configuration.
+
+    Returns:
+        GitHubHandler: An instance of GitHubHandler configured with the provided parameters.
+    """
+    config_file = Path(tool_config.config_file_path)
+    repo = git.Repo(path=config_file.parent, search_parent_directories=True)
+
+    return GitHubHandler(
+        config=GitHubConfig(**handler_config),
+        repo=repo,
+        **kwargs,
+    )

mkdocstrings_handlers/github/objects.py

@@ -0,0 +1,216 @@
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from enum import Enum
+from os import PathLike
+from typing import Any, Literal, Optional
+
+import yaml
+
+
+@dataclass
+class Input:
+    name: str
+    description: str = ""
+    required: bool = False
+    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)
+
+
+@dataclass
+class Output:
+    name: str
+    description: str = ""
+
+    @staticmethod
+    def from_data(name: str, description: str = "", **kwargs) -> "Output":
+        return Output(name, description)
+
+
+@dataclass
+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)
+
+
+def _get_member(d: dict, key: str, error_message: str = "", default: Any = None) -> Any:
+    if key not in d:
+        if default is not None:
+            return default
+        raise KeyError(error_message)
+    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)
+    return source, data
+
+
+@dataclass
+class Action:
+    # https://docs.github.com/en/actions/reference/workflows-and-actions/metadata-syntax
+    file: PathLike
+    source: str
+    id: str
+    name: str
+    description: str
+    using: str
+    author: str = ""
+    inputs: list[Input] = field(default_factory=list)
+    outputs: list[Output] = field(default_factory=list)
+    branding: dict = field(default_factory=dict)
+    template: Literal["action.html.jinja"] = "action.html.jinja"
+
+    @staticmethod
+    def from_file(file: PathLike, id: str) -> "Action":
+        source, data = _read_file(file)
+
+        action = Action(
+            file=file,
+            source=source,
+            id=id,
+            name=_get_member(data, "name", "Action must have a name"),
+            description=_get_member(data, "description", "Action must have a description"),
+            using=_get_member(data, "runs", "Action must have a 'runs' section").get("using", ""),
+            author=_get_member(data, "author", default=""),
+            branding=_get_member(data, "branding", default={}),
+        )
+        for key, value in data.get("inputs", {}).items():
+            action.inputs.append(Input.from_data(key, **value))
+        for key, value in data.get("outputs", {}).items():
+            action.outputs.append(Output.from_data(key, **value))
+        return action
+
+
+class PermissionLevel(Enum):
+    none = ("none", 0)
+    read = ("read", 1)
+    write = ("write", 2)
+
+    @property
+    def label(self) -> str:
+        return self.value[0]
+
+    @property
+    def number(self) -> int:
+        return self.value[1]
+
+    @staticmethod
+    def from_label(label: str) -> "PermissionLevel":
+        for perm in PermissionLevel:
+            if perm.label == label:
+                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
+        return NotImplemented
+
+
+@dataclass
+class Workflow:
+    # https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
+    file: PathLike
+    source: str
+    id: str
+    name: str
+    description: str
+    permissions: dict[str, PermissionLevel] = field(default_factory=dict)
+    inputs: list[Input] = field(default_factory=list)
+    secrets: list[Secret] = field(default_factory=list)
+    outputs: list[Output] = field(default_factory=list)
+    template: Literal["workflow.html.jinja"] = "workflow.html.jinja"
+
+    @staticmethod
+    def from_file(file: PathLike, id: str) -> "Workflow | None":
+        source, data = _read_file(file)
+
+        if "on" not in data or "workflow_call" not in data["on"]:
+            return None
+        call = data["on"]["workflow_call"]
+
+        workflow = Workflow(
+            file=file,
+            source=source,
+            id=id,
+            name=_get_member(data, "name", "Workflow must have a name"),
+            description=_get_member(data, "description", default=""),
+        )
+        for key, value in call.get("inputs", {}).items():
+            workflow.inputs.append(Input.from_data(key, **value))
+        for key, value in call.get("outputs", {}).items():
+            workflow.outputs.append(Output.from_data(key, **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)
+        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)
+        return workflow

mkdocstrings_handlers/github/rendering.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Sequence
+
+from jinja2 import pass_context
+
+from mkdocstrings_handlers.github.config import PARAMETERS_ORDER, GitHubOptions
+from mkdocstrings_handlers.github.objects import Input, Output, Secret
+
+if TYPE_CHECKING:
+    from git import Repo
+    from jinja2.runtime import Context
+
+
+ENV_MAJOR_TAG = "MKDOCSTRINGS_GITHUB_MAJOR_TAG"
+ENV_SEMVER_TAG = "MKDOCSTRINGS_GITHUB_SEMVER_TAG"
+
+
+@pass_context
+def format_action_signature(context: Context, id: str, repo: str, options: GitHubOptions) -> str:
+    name = repo if id == "." else f"{repo}/{id}"
+    match options.signature_version:
+        case "ref":
+            try:
+                repo: Repo = context.environment.globals["git_repo"]
+                version = repo.head.ref.name
+            except Exception:
+                version = "unknown"
+        case "major":
+            version = os.environ.get(ENV_MAJOR_TAG, context.environment.globals["major_tag"])
+        case "semver":
+            version = os.environ.get(ENV_SEMVER_TAG, context.environment.globals["semver_tag"])
+        case "string":
+            version = options.signature_version_string
+
+    return f"{name}@{version}"
+
+
+def order_parameters(
+    parameters: Sequence[Input | Output | Secret], parameters_order: PARAMETERS_ORDER
+):
+    if parameters_order == "alphabetical":
+        return sorted(parameters, key=lambda x: x.name)
+    else:
+        return parameters
+
+
+def filter_parameters(
+    parameters: Sequence[Input | Output | Secret],
+    required: bool = False,
+    optional: bool = False,
+    description: bool = False,
+    default: bool = False,
+):
+    filtered = []
+    for parameter in parameters:
+        filter = False
+        if required and not getattr(parameter, "required", False):
+            filter = True
+        if optional and getattr(parameter, "required", False):
+            filter = True
+        if description and not getattr(parameter, "description", ""):
+            filter = True
+        if default and not getattr(parameter, "default", None):
+            filter = True
+        if not filter:
+            filtered.append(parameter)
+    return filtered

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

@@ -0,0 +1,73 @@
+{#- Template for GitHub Action.
+
+This template renders a GitHub Action.
+
+Context:
+  data (mkdocstrings_handlers.github.objects.Action): The action to render.
+  config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
+  options (dict): The local options
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering " + data.id) }}
+{% endblock logs %}
+
+{% if options.show_branding %}
+  <script src="{{ config.feather_icons_source }}"></script>
+{% endif %}
+<div class="doc doc-object doc-action">
+
+  {% include "heading.html.jinja" with context %}
+
+  {% set signature = data.id | format_action_signature(config.repo, options) %}
+
+  {% block signature scoped %}
+    {% if options.show_signature %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+        {% filter highlight(language="yaml", inline=False, linenums=False) %}
+          - uses: {{ signature }}
+            with:
+              {%+ for input in inputs %}{{ input.name }}: ''{% endfor +%}
+        {% endfilter %}
+      {% 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) }}
+    {% endif %}
+  {% endblock description %}
+
+  {% block inputs scoped %}
+    {% if options.show_inputs %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=options.show_inputs_only_required) %}
+        {% include "inputs.html.jinja" with context %}
+      {% endwith %}
+    {% endif %}
+  {% endblock inputs %}
+
+  {% block outputs scoped %}
+    {% if options.show_outputs %}
+      {% with outputs = data.outputs | order_parameters(options.parameters_order) %}
+        {% include "outputs.html.jinja" with context %}
+      {% endwith %}
+    {% endif %}
+  {% endblock outputs %}
+
+  {% block source scoped %}
+    {% if options.show_source %}
+      <details class="quote">
+        <summary>Source of <code>{{ signature }}</code></summary>
+        {{ data.source|highlight(language="yaml", linenums=True) }}
+      </details>
+    {% endif %}
+  {% endblock %}
+</div>
+{% if options.show_branding %}
+  <script>feather.replace()</script>
+{% endif %}

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

@@ -0,0 +1,39 @@
+{#- Template for heading
+
+Context:
+  data (mkdocstrings_handlers.github.objects.Action | Workfow): The object to render.
+  config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
+  options (dict): The local options
+-#}
+
+{% if options.show_heading %}
+{% filter heading(
+    options.heading_level,
+    role="gh",
+    id=data.id,
+    class="doc doc-heading",
+    toc_label=options.toc_label if options.toc_label else data.name,
+)%}
+    {% block heading scoped %}
+    {% if options.show_branding and (options.branding_icon or data.branding) and (options.branding_icon_color or data.branding.icon) %}
+        <span style="display: inline-flex; align-items: center;">
+        <span class="gh-action-badge-img gh-action-badge--{{ options.branding_icon_color or data.branding.color }}" style="margin-right: 0.5em;">
+            <i data-feather="{{ options.branding_icon or data.branding.icon }}"></i>
+        </span>
+        {{ options.heading if options.heading else data.name }}
+        </span>
+    {% else %}
+        {{ options.heading if options.heading else data.name }}
+    {% endif %}
+    {% endblock heading %}
+{% endfilter %}
+{% elif options.show_toc_entry %}
+{% filter heading(
+    options.heading_level,
+    role="gh",
+    id=data.id,
+    class="doc doc-heading",
+    toc_label=options.toc_label if options.toc_label else data.name,
+)%}
+{% endfilter %}
+{% endif %}

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

@@ -0,0 +1,94 @@
+{#- Template for inputs.
+
+Context:
+  inputs (list of mkdocstrings_handlers.github.objects.Input): The inputs to render.
+  data (mkdocstrings_handlers.github.objects.Action | Workflow): The object to render.
+  config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
+  options (dict): The local options
+-#}
+
+{% block logs scoped %}
+  {{ log.debug("Rendering inputs of " + data.id) }}
+{% endblock logs %}
+
+{% set header_id -%}
+  inputs-{{ data.id | replace('/', '-') | replace('.', '') | lower }}
+{%- endset %}
+
+{% if options.parameters_section_style == "table" %}
+  {% block table_style scoped %}
+    <p>
+      <span class="doc-section-title">Inputs:</span>
+      <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
+    </p>
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for input in inputs %}
+          {% if options.parameters_anchors %}
+            {% set anchor_id -%}
+              input-{{ data.id | replace('/', '-') | replace('.', '') | lower }}-{{ input.name | replace(' ', '-') | lower }}
+            {%- endset %}
+          {% else %}
+            {% set anchor_id = None %}
+          {% endif %}
+          <tr class="doc-section-item">
+            <td id="{{ anchor_id }}">
+              {% if input.required %}
+                <strong><code>{{ input.name }}</code></strong>
+              {% else %}
+                <code>{{ input.name }}</code>
+              {% endif %}
+              {% if options.parameters_anchors %}
+                <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ input.name }}">¤</a>
+              {% endif %}
+            </td>
+            <td>
+              {{ input.description | convert_markdown(options.heading_level, data.id) }}
+            </td>
+            <td>
+              {% if input.default %}
+                <code>{{ input.default }}</code>
+              {% endif %}
+            </td>
+          </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endblock table_style %}
+{% elif options.parameters_section_style == "list" %}
+  {% block list_style scoped %}
+    <p>
+      <span class="doc-section-title">Inputs:</span>
+      <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
+    </p>
+    <ul>
+      {% for input in inputs %}
+        {% set anchor_id -%}
+          input-{{ data.id | replace('/', '-') | replace('.', '') | lower }}-{{ input.name | replace(' ', '-') | lower }}
+        {%- endset %}
+        <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 }}</code>
+            </div>
+          {% endif %}
+        </li>
+      {% endfor %}
+    </ul>
+  {% endblock list_style %}
+{% endif %}

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

@@ -0,0 +1,78 @@
+{#- Template for outputs.
+
+Context:
+  outputs (list of mkdocstrings_handlers.github.objects.Output): The outputs to render.
+  data (mkdocstrings_handlers.github.objects.Action | Workflow): The object to render.
+  config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
+  options (dict): The local options
+-#}
+
+{% block logs scoped %}
+  {{ log.debug("Rendering outputs of " + data.id) }}
+{% endblock logs %}
+
+{% set header_id -%}
+  outputs-{{ data.id | replace('/', '-') | replace('.', '') | lower }}
+{%- endset %}
+
+{% if options.parameters_section_style == "table" %}
+  {% block table_style scoped %}
+    <p>
+      <span class="doc-section-title">Outputs:</span>
+      <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
+    </p>
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for output in outputs %}
+          {% if options.parameters_anchors %}
+            {% set anchor_id -%}
+              output-{{ data.id | replace('/', '-') | replace('.', '') | lower }}-{{ output.name | replace(' ', '-') | lower }}
+            {%- endset %}
+          {% else %}
+            {% set anchor_id = None %}
+          {% endif %}
+          <tr class="doc-section-item">
+            <td id="{{ anchor_id }}">
+              <code>{{ output.name }}</code>
+              {% if options.parameters_anchors %}
+                <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ output.name }}">¤</a>
+              {% endif %}
+            </td>
+            <td>
+              {{ output.description | convert_markdown(options.heading_level, data.id) }}
+            </td>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endblock table_style %}
+{% elif options.parameters_section_style == "list" %}
+  {% block list_style scoped %}
+    <p>
+      <span class="doc-section-title">Outputs:</span>
+      <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
+    </p>
+    <ul>
+      {% for output in outputs %}
+        {% set anchor_id -%}
+          output-{{ data.id | replace('/', '-') | replace('.', '') | lower }}-{{ output.name | replace(' ', '-') | lower }}
+        {%- endset %}
+        <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 %}
+    </ul>
+  {% endblock list_style %}
+{% endif %}
+

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

@@ -0,0 +1,82 @@
+{#- Template for secrets.
+
+Context:
+  secrets (list of mkdocstrings_handlers.github.objects.Secret): The secrets to render.
+  data (mkdocstrings_handlers.github.objects.Workflow): The object to render.
+  config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
+  options (dict): The local options
+-#}
+
+{% block logs scoped %}
+  {{ log.debug("Rendering secrets of " + data.id) }}
+{% endblock logs %}
+
+{% set header_id -%}
+  secrets-{{ data.id | replace('/', '-') | replace('.', '') | lower }}
+{%- endset %}
+
+{% if options.parameters_section_style == "table" %}
+  {% block table_style scoped %}
+    <p>
+      <span class="doc-section-title">Secrets:</span>
+      <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
+    </p>
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for secret in secrets %}
+          {% if options.parameters_anchors %}
+            {% set anchor_id -%}
+              secret-{{ data.id | replace('/', '-') | replace('.', '') | lower }}-{{ secret.name | replace(' ', '-') | lower }}
+            {%- endset %}
+          {% else %}
+            {% set anchor_id = None %}
+          {% endif %}
+          <tr class="doc-section-item">
+           <td id="{{ anchor_id }}">
+              {% if secret.required %}
+                <strong><code>{{ secret.name }}</code></strong>
+              {% else %}
+                <code>{{ secret.name }}</code>
+              {% endif %}
+              {% if options.parameters_anchors %}
+                <a class="headerlink" href="#{{ anchor_id }}" title="Link to {{ secret.name }}">¤</a>
+              {% endif %}
+            </td>
+            <td>
+              {{ secret.description | convert_markdown(options.heading_level, data.id) }}
+            </td>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endblock table_style %}
+{% elif options.parameters_section_style == "list" %}
+  {% block list_style scoped %}
+    <p>
+      <span class="doc-section-title">Secrets:</span>
+      <a class="headerlink" href="#{{ header_id }}" title="Link to {{ data.name }} outputs">¤</a>
+    </p>
+    <ul>
+      {% for secret in secrets %}
+        {% set anchor_id -%}
+          secret-{{ data.id | replace('/', '-') | replace('.', '') | lower }}-{{ secret.name | replace(' ', '-') | lower }}
+        {%- endset %}
+        <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 %}
+    </ul>
+  {% endblock list_style %}
+{% endif %}

mkdocstrings_handlers/github/templates/material/style.css

@@ -0,0 +1,59 @@
+/* .gh-action-badge {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  width: 140px;
+  margin: 15px 5px;
+  cursor: copy;
+} */
+
+.gh-action-badge-img {
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  box-shadow: 0 1px 5px rgba(27,31,35,.15);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  margin: 3px;
+}
+
+.gh-action-badge--white {
+  background-color: #ffffff;
+  color: #23292e;
+}
+
+.gh-action-badge--yellow {
+  background-color: #ffd33d;
+  color: #23292e;
+}
+
+.gh-action-badge--blue {
+  background-color: #0366d6;
+  color: #ffffff;
+}
+
+.gh-action-badge--green {
+  background-color: #28a745;
+  color: #ffffff;
+}
+
+.gh-action-badge--orange {
+  background-color: #f66a0a;
+  color: #ffffff;
+}
+
+.gh-action-badge--red {
+  background-color: #d73a49;
+  color: #ffffff;
+}
+
+.gh-action-badge--purple {
+  background-color: #6f42c1;
+  color: #ffffff;
+}
+
+.gh-action-badge--gray-dark {
+  background-color: #24292e;
+  color: #ffffff;
+}

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

@@ -0,0 +1,90 @@
+{#- Template for GitHub Action reusable workflow.
+
+Context:
+  data (mkdocstrings_handlers.github.objects.Workflow): The workflow to render.
+  config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
+  options (dict): The local options
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering " + data.id) }}
+{% endblock logs %}
+
+{% if options.show_branding %}
+  <script src="{{ config.feather_icons_source }}"></script>
+{% endif %}
+<div class="doc doc-object doc-workflow">
+  {% include "heading.html.jinja" with context %}
+
+  {% set signature = data.id | format_action_signature(config.repo, options) %}
+
+  {% block signature scoped %}
+    {% if options.show_signature %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+        {% filter highlight(language="yaml", inline=False, linenums=False) %}
+          uses: {{ signature }}
+          {% if options.signature_show_permissions and data.permissions %}
+          permissions:
+            {% for scope, level in data.permissions | items %}
+            {{ scope }}: {{ level.label }}
+            {% endfor %}
+          {% endif %}
+          with:
+            {%+ for input in inputs %}{{ input.name }}: ''{% endfor +%}
+          {% if options.signature_show_secrets %}
+            {% with secrets = data.secrets | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+          secrets:
+            {%+ for secret in secrets %}{{ secret.name }}: ''{% endfor +%}
+            {% endwith %}
+          {% endif %}
+        {% endfilter %}
+      {% 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) }}
+    {% endif %}
+  {% endblock description %}
+
+  {% block inputs scoped %}
+    {% if options.show_inputs %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=options.show_inputs_only_required) %}
+        {% include "inputs.html.jinja" with context %}
+      {% endwith %}
+    {% endif %}
+  {% endblock inputs %}
+
+  {% block secrets scoped %}
+    {% if options.show_secrets %}
+      {% with secrets = data.secrets | order_parameters(options.parameters_order) | filter_parameters(required=options.show_secrets_only_required) %}
+        {% include "secrets.html.jinja" with context %}
+      {% endwith %}
+    {% endif %}
+  {% endblock secrets %}
+
+  {% block outputs scoped %}
+    {% if options.show_outputs %}
+      {% with outputs = data.outputs | order_parameters(options.parameters_order) %}
+        {% include "outputs.html.jinja" with context %}
+      {% endwith %}
+    {% endif %}
+  {% endblock outputs %}
+
+  {% block source scoped %}
+    {% if options.show_source %}
+      <details class="quote">
+        <summary>Source of <code>{{ signature }}</code></summary>
+        {{ data.source|highlight(language="yaml", linenums=True) }}
+      </details>
+    {% endif %}
+  {% endblock %}
+</div>
+{% if options.show_branding %}
+  <script>feather.replace()</script>
+{% endif %}