mkdocstrings-github 0.5.0__tar.gz → 0.6.0__tar.gz

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/.github/CONTRIBUTING.md

@@ -2,7 +2,18 @@
 
 Thank you for considering contributing! Please follow these steps to get started:
 
-## 1. Environment Setup
+## 1. Clone repository
+
+Clone the repository and setup its submodules. The [watermarkhu/mkdocstrings-github-fixture](https://github.com/watermarkhu/mkdocstrings-github-fixture) repository is used as a fixture repository. 
+
+```sh
+git clone https://github.com/watermarkhu/mkdocstrings-github
+cd mkdocstrings-github
+git submodule init
+git submodule update
+```
+
+## 2. Environment Setup
 
 Install all dependencies using [uv](https://github.com/astral-sh/uv):
 
@@ -12,7 +23,7 @@ uv sync --all-groups
 
 Learn more about uv: [uv documentation](https://github.com/astral-sh/uv)
 
-## 2. Pre-commit Hooks using prek
+## 3. Pre-commit Hooks using prek
 
 Set up [prek](https://github.com/j178/prek) hooks to ensure code quality:
 
@@ -22,7 +33,7 @@ uv run prek install
 
 See: [prek documentation](https://prek.j178.dev/)
 
-## 3. Running Tests
+## 4. Running Tests
 
 Run tests with [pytest](https://docs.pytest.org/en/stable/):
 
@@ -32,7 +43,7 @@ uv run pytest
 
 See: [pytest documentation](https://docs.pytest.org/en/stable/)
 
-## 4. Pull Request Guidelines
+## 5. Pull Request Guidelines
 
 - Pull requests should target the `main` branch.
 - Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/.github/workflows/example_workflow.yml

@@ -4,7 +4,7 @@ description: "This key is illegal but will still be parsed"
 on:
   workflow_call:
     inputs:
-      environment:
+      environment: # group: environment
         description: |
           Environment to deploy to. Must be one of 
 
@@ -13,6 +13,11 @@ on:
           - `production`
         required: true
         type: string
+      configuration: # group: environment
+        description: 'JSON configuration object'
+        required: false
+        type: string
+        default: '{}'
       version:
         description: 'Version to deploy'
         required: false
@@ -28,26 +33,22 @@ on:
         required: false
         type: number
         default: 1
-      configuration:
-        description: 'JSON configuration object'
-        required: false
-        type: string
-        default: '{}'
+
     secrets:
-      API_KEY:
+      API_KEY: # group: environment
         description: 'API key for external service'
         required: true
-      DATABASE_URL:
+      DATABASE_URL: # group: environment
         description: 'Database connection string'
         required: false
       SLACK_WEBHOOK:
         description: 'Slack webhook URL for notifications'
         required: false
     outputs:
-      deployment-id:
+      deployment-id: # group: deployment
         description: 'ID of the created deployment'
         value: ${{ jobs.deploy.outputs.deployment-id }}
-      deployment-url:
+      deployment-url: # group: deployment
         description: 'URL of the deployment'
         value: ${{ jobs.deploy.outputs.deployment-url }}
       success:

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/.github/workflows/qualify.yaml

@@ -127,7 +127,7 @@ jobs:
 
     - name: Upload Test Results
       if: (!cancelled())
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: python${{ matrix.python-version }}
         path: "*.xml"
@@ -148,7 +148,7 @@ jobs:
           fetch-depth: 2
 
       - name: Download Artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v6
         with:
           path: results
 

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.5.0
+Version: 0.6.0
 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
 
@@ -83,5 +83,6 @@ after which the generated documentation can be inserted in the markdown page wit
 - 🧩 **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.5.0 → mkdocstrings_github-0.6.0}/README.md

@@ -54,5 +54,6 @@ after which the generated documentation can be inserted in the markdown page wit
 - 🧩 **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.5.0 → mkdocstrings_github-0.6.0}/action.yaml

@@ -6,15 +6,15 @@ branding:
   color: 'blue'
 
 inputs:
-  repository:
+  repository: # group: Repository Options
     description: 'Repository name with owner. For example, actions/checkout'
     default: ${{ github.repository }}
-  ref:
+  ref: # group: Repository Options
     description: >
       The branch, tag or SHA to checkout. When checking out the repository that
       triggered a workflow, this defaults to the reference or SHA for that
       event.  Otherwise, uses the default branch.
-  token:
+  token: # group: Authentication
     description: >
       Personal access token (PAT) used to fetch the repository. The PAT is configured
       with the local git config, which enables your scripts to run authenticated git
@@ -27,7 +27,7 @@ inputs:
 
       [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
     default: ${{ github.token }}
-  ssh-key:
+  ssh-key: # group: Authentication
     description: >
       SSH key used to fetch the repository. The SSH key is configured with the local
       git config, which enables your scripts to run authenticated git commands.
@@ -39,35 +39,35 @@ inputs:
 
       [Learn more about creating and using
       encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
-  ssh-known-hosts:
+  ssh-known-hosts: # group: Authentication
     description: >
       Known hosts in addition to the user and global host key database. The public
       SSH keys for a host may be obtained using the utility `ssh-keyscan`. For example,
       `ssh-keyscan github.com`. The public key for github.com is always implicitly added.
-  ssh-strict:
+  ssh-strict: # group: Authentication
     description: >
       Whether to perform strict host key checking. When true, adds the options `StrictHostKeyChecking=yes`
       and `CheckHostIP=no` to the SSH command line. Use the input `ssh-known-hosts` to
       configure additional hosts.
     default: true
-  ssh-user:
+  ssh-user: # group: Authentication
     description: >
       The user to use when connecting to the remote SSH host. By default 'git' is used.
     default: git
-  persist-credentials:
+  persist-credentials: # group: Authentication
     description: 'Whether to configure the token or SSH key with the local git config'
     default: true
-  path:
+  path: # group: Repository Options
     description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
-  clean:
+  clean: # group: Repository Options
     description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
     default: true
-  filter:
+  filter: # group: Repository Options
     description: >
       Partially clone against a given filter.
       Overrides sparse-checkout if set.
     default: null
-  sparse-checkout:
+  sparse-checkout:  # group: Repository Options
     description: >
       Do a sparse checkout on given patterns.
       Each pattern should be separated with new lines.

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/docs/changelog.md

@@ -2,6 +2,40 @@
 
 <!-- version list -->
 
+## v0.6.0 (2025-10-27)
+
+### Build System
+
+- **deps**: Update dependency inline-snapshot to ~=0.30.0
+  ([#35](https://github.com/watermarkhu/mkdocstrings-github/pull/35),
+  [`8e8214d`](https://github.com/watermarkhu/mkdocstrings-github/commit/8e8214d31f875a2921fa007248153e71179d0407))
+
+### Continuous Integration
+
+- **deps**: Update group-github-actions
+  ([#36](https://github.com/watermarkhu/mkdocstrings-github/pull/36),
+  [`1e13659`](https://github.com/watermarkhu/mkdocstrings-github/commit/1e13659585994c534f817e76bd530ec96e134bc3))
+
+- **deps**: Update group-github-actions (major)
+  ([#36](https://github.com/watermarkhu/mkdocstrings-github/pull/36),
+  [`1e13659`](https://github.com/watermarkhu/mkdocstrings-github/commit/1e13659585994c534f817e76bd530ec96e134bc3))
+
+### Features
+
+- Add parameter grouping, ruamel.yaml
+  ([#37](https://github.com/watermarkhu/mkdocstrings-github/pull/37),
+  [`c6d8681`](https://github.com/watermarkhu/mkdocstrings-github/commit/c6d8681281adefe935f6abfb009257301fc6537f))
+
+
+## v0.5.1 (2025-10-14)
+
+### Bug Fixes
+
+- Do not validate signature_repository
+  ([#34](https://github.com/watermarkhu/mkdocstrings-github/pull/34),
+  [`3ead525`](https://github.com/watermarkhu/mkdocstrings-github/commit/3ead5253eb68e9a5fb5def55e807801afc1ef106))
+
+
 ## v0.5.0 (2025-10-13)
 
 ### Bug Fixes

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/docs/index.md

@@ -32,5 +32,6 @@ hide:
             signature_version: string
             signature_version_string: v5
             signature_repository: actions/checkout
+            parameters_groups: true
             show_source: false
     </div>

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/docs/usage/parameters.md

@@ -133,6 +133,60 @@
             options:
                 parameters_section_style: 'list'
 
+::: mkdocstrings_handlers.github.config.GitHubOptions.parameters_groups
+    handler: python
+
+??? preview
+
+    === "`parameters_groups: true` (table)"
+        
+        ::: .github/workflows/example_workflow.yml
+            options:
+                parameters_groups: true
+                parameters_section_style: 'table'
+
+    === "`parameters_groups: false` (table)"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                parameters_groups: false
+                parameters_section_style: 'table'
+
+    === "`parameters_groups: true` (list)"
+        
+        ::: .github/workflows/example_workflow.yml
+            options:
+                parameters_groups: true
+                parameters_section_style: 'list'
+
+    === "`parameters_groups: false` (list)"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                parameters_groups: false
+                parameters_section_style: 'list'
+
+::: mkdocstrings_handlers.github.config.GitHubOptions.parameters_group_title_row
+    handler: python
+
+??? preview
+
+    === "`parameters_group_title_row: true`"
+        
+        ::: .github/workflows/example_workflow.yml
+            options:
+                parameters_groups: true
+                parameters_group_title_row: true
+                parameters_section_style: 'table'
+
+    === "`parameters_group_title_row: false`"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                parameters_groups: true
+                parameters_group_title_row: false
+                parameters_section_style: 'table'
+
 ::: mkdocstrings_handlers.github.config.GitHubOptions.parameters_anchors
     handler: python
 

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/docs/usage/signatures.md

@@ -41,7 +41,7 @@
 
 ??? preview
 
-    === "`signature_repository: 'username/repo'`"
+    === "`signature_repository: username/repo`"
 
         ::: .github/workflows/example_workflow.yml
             options:

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/mkdocs.yml

@@ -1,12 +1,18 @@
-site_name: "mkdocstrings-github"
-site_description: "A MATLAB handler for mkdocstrings."
-site_url: "https://watermarkhu.nl/mkdocstrings-github"
-repo_url: "https://github.com/watermarkhu/mkdocstrings-github"
-repo_name: "watermarkhu/mkdocstrings-github"
-watch: [mkdocs.yml, README.md, src/mkdocstrings_handlers]
+site_name: mkdocstrings-github
+site_description: A MATLAB handler for mkdocstrings.
+site_url: https://watermarkhu.nl/mkdocstrings-github
+repo_url: https://github.com/watermarkhu/mkdocstrings-github
+repo_name: watermarkhu/mkdocstrings-github
 copyright: Copyright © 2025 Mark Shui Hu
 edit_uri: edit/main/docs/
 
+watch: 
+  - mkdocs.yml
+  - README.md
+  - src/mkdocstrings_handlers
+  - action.yaml
+  - .github
+
 validation:
   omitted_files: warn
   absolute_links: warn
@@ -108,7 +114,7 @@ markdown_extensions:
 - pymdownx.tasklist:
     custom_checkbox: true
 - toc:
-    permalink: "¤"
+    permalink: ¤
     toc_depth: 2
 
 plugins:
@@ -124,8 +130,11 @@ plugins:
           show_toc_entry: false
           heading_level: 3
           parameters_anchors: false
+          parameters_groups: false
+          parameters_group_title_row: true
           signature_version: string
           signature_version_string: v1
+
       python:
         paths: [src]
         options:

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-github"
-version = "0.5.0"
+version = "0.6.0"
 description = "A GitHub Action handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
@@ -27,9 +27,9 @@ classifiers = [
 ]
 
 dependencies = [
-    "gitpython~=3.1.45",
-    "mkdocstrings~=0.29",
-    "packaging~=25.0",
+    "gitpython>=3.1.45,<4",
+    "mkdocstrings>=0.29,<1",
+    "ruamel.yaml>=0.18.16,<1",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
 
@@ -42,7 +42,7 @@ dev = [
     "pytest~=8.4.1",
     "pytest-cov~=7.0.0",
     "beautifulsoup4>=4.13.3",
-    "inline-snapshot~=0.29.0",
+    "inline-snapshot~=0.30.0",
     "python-semantic-release~=10.4.1",
 ]
 docs = [

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/src/mkdocstrings_handlers/github/config.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import re
 import sys
 from typing import Literal
 
@@ -99,7 +98,6 @@ class GitHubOptions(BaseModel):
         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.-]+$"),
     )
 
     signature_show_secrets: bool = Field(
@@ -172,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.",

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/src/mkdocstrings_handlers/github/handler.py

@@ -170,6 +170,7 @@ 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

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/src/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
 
 
@@ -121,9 +98,9 @@ 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
 
 
@@ -218,11 +195,11 @@ 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))
+                workflow.secrets.append(Secret(name=key, **value, group=group_from_map(value)))
 
         def set_all_permissions(level: str):
             if level == "read-all":

{mkdocstrings_github-0.5.0 → mkdocstrings_github-0.6.0}/src/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
@@ -40,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
 ):