mkdocstrings-github 0.6.4__tar.gz → 0.7.0__tar.gz

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/.github/workflows/example_workflow.yml

@@ -70,16 +70,10 @@ jobs:
     name: 'Validate Inputs'
     runs-on: ubuntu-latest
     steps:
-      - name: Validate environment
-        run: |
-          echo "Validating environment: ${{ inputs.environment }}"
-          if [[ ! "${{ inputs.environment }}" =~ ^(development|staging|production)$ ]]; then
-            echo "Error: Invalid environment specified"
-            exit 1
-          fi
+      - name: Checkout code
+        uses: actions/checkout@v4
           
-      - name: Validate version
-        run: |
+      - run: |
           echo "Validating version: ${{ inputs.version }}"
           
       - name: Check secrets
@@ -106,8 +100,7 @@ jobs:
           echo "Parallel jobs: ${{ inputs.parallel-jobs }}"
           echo "Notifications enabled: ${{ inputs.enable-notifications }}"
           
-      - name: Parse configuration
-        run: |
+      - run: |
           echo "Configuration: ${{ inputs.configuration }}"
           
       - name: Execute deployment
@@ -125,15 +118,12 @@ jobs:
           echo "URL: ${deployment_url}"
 
   notify:
-    name: 'Send Notifications'
-    runs-on: ubuntu-latest
+    name: Send Notifications
+    uses: other-org/notify-workflow/.github/workflows/notify.yml@main
     needs: deploy
-    if: ${{ inputs.enable-notifications }}
-    steps:
-      - name: Send Slack notification
-        run: |
-          echo "Sending Slack notification about deployment ${{ needs.deploy.outputs.deployment-id }}"
-          
-      - name: Create GitHub deployment
-        run: |
-          echo "Creating GitHub deployment status for ${{ needs.deploy.outputs.deployment-id }}"
+    if: ${{ inputs.enable-notifications == true }}
+    with:
+      deployment-id: ${{ needs.deploy.outputs.deployment-id }}
+      deployment-url: ${{ needs.deploy.outputs.deployment-url }}
+      environment: ${{ inputs.environment }}
+      success: ${{ needs.deploy.outputs.success }}

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.6.4
+Version: 0.7.0
 Summary: A GitHub Action handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/docs/changelog.md

@@ -2,6 +2,19 @@
 
 <!-- version list -->
 
+## v0.7.0 (2026-01-13)
+
+### Features
+
+- Workflow flowcharts ([#43](https://github.com/watermarkhu/mkdocstrings-github/pull/43),
+  [`f013ad8`](https://github.com/watermarkhu/mkdocstrings-github/commit/f013ad83add0b4d9ab04b634fc595891445a59c0))
+
+### Testing
+
+- Fix snapshots ([#43](https://github.com/watermarkhu/mkdocstrings-github/pull/43),
+  [`f013ad8`](https://github.com/watermarkhu/mkdocstrings-github/commit/f013ad83add0b4d9ab04b634fc595891445a59c0))
+
+
 ## v0.6.4 (2026-01-13)
 
 ### Chores

mkdocstrings_github-0.7.0/docs/usage/general.md

@@ -0,0 +1,119 @@
+# General options
+
+??? info "Example action/workflow"
+
+    ??? preview "compsite action `action.yaml`"
+
+        ```yaml title="action.yaml"
+        --8<-- "action.yaml"
+        ```
+
+    ??? preview "reusable workflow `.github/workflows/example_workflow.yml`"
+
+        ```yaml title=".github/workflows/example_workflow.yml"
+        --8<-- ".github/workflows/example_workflow.yml"
+        ```
+
+
+::: mkdocstrings_handlers.github.config.GitHubOptions.show_description
+    handler: python
+
+??? preview
+
+    === "`show_description: true`"
+
+        ::: .
+            options:
+                show_description: true
+
+    === "`show_description: false`"
+
+        ::: .
+            options:
+                show_description: false
+
+::: mkdocstrings_handlers.github.config.GitHubOptions.description
+    handler: python
+
+??? preview
+
+    === "`description: ''`"
+
+        ::: .
+
+    === "`description: 'A custom description'`"
+
+        ::: .
+            options:
+               description: 'A custom description'
+
+::: mkdocstrings_handlers.github.config.GitHubOptions.show_source
+    handler: python
+
+??? preview
+
+    === "`show_source: true`"
+
+        ::: .
+            options:
+                show_source: true
+
+    === "`show_source: false`"
+
+        ::: .
+            options:
+                show_source: false
+
+::: mkdocstrings_handlers.github.config.GitHubOptions.workflow_chart
+    handler: python
+
+In order to display the mermaid diagram, you'll need to setup the configuration for [Mermaid.js](https://mermaid.ai/) in [mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/diagrams/#configuration) or via [mkdocs-mermaid2](https://mkdocs-mermaid2.readthedocs.io). Following the instructions in the linked pages to configure your `mkdocs.yml`. Additionally, we recommend setting up [Panzoom for MkDocs](https://github.com/PLAYG0N/mkdocs-panzoom), which allows zooming into the displayed diagram. 
+
+In the output diagram, each step in a job is represented as a node, jobs are represented as groups, and dependencies between jobs are displayed as edges between groups. Steps that call actions are rounded. Jobs that call another workflow are shown as a subroutine. Jobs and steps without `name` are **omitted** from the graph.
+
+```mermaid
+flowchart TB
+    subgraph JobA
+        direction LR
+        a1(Checkout) --> a2["Shell step"]
+    end
+    subgraph JobB
+        direction LR
+        b1 --> b2
+    end
+    JobA -.-> JobB
+    JobB -.-> Workflow[["Workflow call"]]
+```
+
+??? preview
+
+    === "`workflow_chart: true`"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                workflow_chart: true
+
+    === "`workflow_chart: false`"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                workflow_chart: false
+
+::: mkdocstrings_handlers.github.config.GitHubOptions.workflow_chart_step_direction
+    handler: python
+
+??? preview
+
+    === "`workflow_chart_step_direction: 'TB'`"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                workflow_chart: true
+                workflow_chart_step_direction: 'TB'
+
+    === "`workflow_chart_step_direction: 'LR'`"
+
+        ::: .github/workflows/example_workflow.yml
+            options:
+                workflow_chart: true
+                workflow_chart_step_direction: 'LR'

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/mkdocs.yml

@@ -6,7 +6,7 @@ repo_name: watermarkhu/mkdocstrings-github
 copyright: Copyright © 2025 Mark Shui Hu
 edit_uri: edit/main/docs/
 
-watch: 
+watch:
   - mkdocs.yml
   - README.md
   - src/mkdocstrings_handlers
@@ -105,7 +105,7 @@ markdown_extensions:
     custom_fences:
     - name: mermaid
       class: mermaid
-      format: !!python/name:pymdownx.superfences.fence_code_format
+      format: !!python/name:mermaid2.fence_mermaid_custom
 - pymdownx.tabbed:
     alternate_style: true
     slugify: !!python/object/apply:pymdownx.slugs.slugify
@@ -121,6 +121,10 @@ plugins:
 - callouts
 - autorefs
 - search
+- mermaid2
+- panzoom:
+    initial_zoom_level: 0.5
+    full_screen: true
 - mkdocstrings:
     default_handler: github
     handlers:

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-github"
-version = "0.6.4"
+version = "0.7.0"
 description = "A GitHub Action handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
@@ -53,6 +53,8 @@ docs = [
     "mkdocstrings-python~=2.0.0",
     "mike~=2.1",
     "griffe-pydantic~=1.2.0",
+    "mkdocs-mermaid2-plugin~=1.2.3",
+    "mkdocs-panzoom-plugin~=0.5.2",
 ]
 
 

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/src/mkdocstrings_handlers/github/config.py

@@ -21,6 +21,7 @@ logger = get_logger(__name__)
 SIGNATURE_VERSION = Literal["ref", "major", "semver", "string"]
 PARAMETERS_ORDER = Literal["alphabetical", "source"]
 PARAMETERS_SECTION_STYLE = Literal["table", "list"]
+STEP_DIRECTION = Literal["TB", "LR"]
 
 
 class GitHubOptions(BaseModel):
@@ -201,6 +202,26 @@ class GitHubOptions(BaseModel):
         description="Whether to add anchors to parameters in the documentation.",
     )
 
+    # Workflow chart option
+    workflow_chart: bool = Field(
+        default=False,
+        description="""Whether to generate a Mermaid flowchart for reusable workflows.
+
+        The flowchart displays the workflow's jobs and steps in a flowchart diagram.
+        Multiple jobs are rendered as subgraphs, and calls to other workflows are visually distinct.
+        The diagram is rendered client-side in the browser using mkdocs-mermaid2.
+        """,
+    )
+
+    workflow_chart_step_direction: STEP_DIRECTION = Field(
+        default="LR",
+        description="""The direction of the flowchart for steps within jobs.
+
+        - `TB`: top-to-bottom layout,
+        - `LR`: left-to-right layout.
+        """,
+    )
+
 
 class GitHubConfig(BaseModel):
     """Configuration options for the GitHub handler."""

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/src/mkdocstrings_handlers/github/handler.py

@@ -173,6 +173,7 @@ class GitHubHandler(BaseHandler):
         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.filters["generate_mermaid_flowchart"] = rendering.generate_mermaid_flowchart
         self.env.globals["semver_tag"] = self.semver
         self.env.globals["major_tag"] = self.major
         self.env.globals["git_repo"] = self.repo

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/src/mkdocstrings_handlers/github/objects.py

@@ -2,7 +2,7 @@ import re
 from dataclasses import dataclass, field
 from enum import Enum
 from os import PathLike
-from typing import Any, Literal, Optional
+from typing import Any, Literal
 
 from ruamel.yaml import YAML
 from ruamel.yaml.comments import CommentedMap
@@ -35,7 +35,7 @@ class Input:
     required: bool = False
     type: Literal["boolean", "number", "string"] = "string"
     default: bool | float | int | str | None = None
-    deprecationMessage: Optional[str] = None
+    deprecationMessage: str | None = None
     group: str = ""
 
 
@@ -55,6 +55,31 @@ class Secret:
     group: str = ""
 
 
+@dataclass
+class Step:
+    """Represents a step within a job."""
+
+    name: str
+    uses: str = ""  # For steps that use actions
+    run: str = ""  # For steps that run commands
+
+
+@dataclass
+class Job:
+    """Represents a job within a workflow."""
+
+    id: str
+    name: str
+    uses: str | None
+    steps: list[Step] = field(default_factory=list)
+    needs: list[str] = field(default_factory=list)  # Job dependencies
+
+    @property
+    def mermaid_id(self) -> str:
+        job_id_safe = self.id.replace("-", "_").replace(".", "_")
+        return f"job_{job_id_safe}"
+
+
 def _get_member(d: dict, key: str, error_message: str = "", default: Any = None) -> Any:
     if key not in d:
         if default is not None:
@@ -164,6 +189,7 @@ class Workflow:
     inputs: list[Input] = field(default_factory=list)
     secrets: list[Secret] = field(default_factory=list)
     outputs: list[Output] = field(default_factory=list)
+    jobs: dict[str, Job] = field(default_factory=dict)
     template: Literal["workflow.html.jinja"] = "workflow.html.jinja"
 
     @property
@@ -221,11 +247,11 @@ class Workflow:
                 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():
-            if isinstance(permissions := job.get("permissions", {}), str):
+        for job_id, job_data in data.get("jobs", {}).items():
+            if isinstance(permissions := job_data.get("permissions", {}), str):
                 set_all_permissions(permissions)
             elif isinstance(permissions, dict):
-                for key, label in job.get("permissions", {}).items():
+                for key, label in job_data.get("permissions", {}).items():
                     if key in workflow.permissions:
                         permission = PermissionLevel.from_label(label)
                         if permission > workflow.permissions[key]:
@@ -235,4 +261,29 @@ class Workflow:
             else:
                 raise ValueError("permissions must be a string or a dictionary")
 
+            # Parse job information for flowchart
+            job = Job(id=job_id, name=job_data.get("name", job_id), uses=job_data.get("uses", None))
+
+            # Parse job dependencies
+            needs = job_data.get("needs", [])
+            if isinstance(needs, str):
+                job.needs = [needs]
+            elif isinstance(needs, list):
+                job.needs = needs
+
+            # Parse steps
+            for step_data in job_data.get("steps", []):
+                step_name = step_data.get("name", "")
+                step_uses = step_data.get("uses", "")
+                step_run = step_data.get("run", "")
+
+                step = Step(
+                    name=step_name,
+                    uses=step_uses,
+                    run=step_run,
+                )
+                job.steps.append(step)
+
+            workflow.jobs[job.id] = job
+
         return workflow

mkdocstrings_github-0.7.0/src/mkdocstrings_handlers/github/rendering.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import os
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Sequence
+
+from jinja2 import pass_context
+
+from mkdocstrings_handlers.github.config import PARAMETERS_ORDER, STEP_DIRECTION, GitHubOptions
+from mkdocstrings_handlers.github.objects import Input, Output, Secret, Workflow
+
+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:
+                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":
+            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 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
+):
+    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
+
+
+def anchor_id(name: str, prefix: str, parent_id: str) -> str:
+    anchor = f"{parent_id}--{prefix}.{name}"
+    return anchor.replace(" ", "-")
+
+
+def as_string(value: bool | str | int | float | None) -> str:
+    match value:
+        case bool():
+            return "true" if value else "false"
+        case str():
+            return value
+        case int() | float():
+            return str(value)
+        case None:
+            return ""
+        case _:
+            raise TypeError(f"Unsupported type: {type(value)}")
+
+
+def generate_mermaid_flowchart(workflow: Workflow, direction: STEP_DIRECTION = "TB") -> str:
+    """Generate a Mermaid flowchart for a reusable workflow.
+
+    Args:
+        workflow: The workflow object containing jobs and steps.
+        direction: The direction of steps within jobs (TB for top-to-bottom, LR for left-to-right).
+
+    Returns:
+        A Mermaid flowchart diagram as a string.
+    """
+    if not workflow.jobs:
+        return ""
+
+    lines = ["flowchart TB"]
+
+    # Track all nodes for dependency linking
+    job_start_nodes = {}
+    job_end_nodes = {}
+
+    for job in workflow.jobs.values():
+        job_id_safe = job.mermaid_id
+
+        # Check if job calls another workflow (has any steps with workflow set)
+        if job.uses is not None:
+            # Job that calls a workflow - render as a single subroutine node
+            lines.append(f'    {job_id_safe}[["{job.name}"]]')
+            job_start_nodes[job.id] = job_id_safe
+            job_end_nodes[job.id] = job_id_safe
+            continue
+
+        # Regular job - render as a subgraph with steps
+
+        lines.append(f'    subgraph {job_id_safe}["{job.name}"]')
+        lines.append(f"        direction {direction}")
+
+        if job.steps:
+            # Filter steps that have a name
+            named_steps = [(idx, step) for idx, step in enumerate(job.steps) if step.name]
+
+            if named_steps:
+                prev_step_id = None
+
+                for idx, step in named_steps:
+                    step_id = f"{job_id_safe}_step_{idx}"
+                    step_name = step.name
+
+                    # Escape special characters in step names
+                    step_name_escaped = (
+                        step_name.replace('"', """).replace("[", "[").replace("]", "]")
+                    )
+
+                    # Determine node style based on step type
+                    if step.uses:
+                        # Action uses get rounded rectangle
+                        lines.append(f'        {step_id}("{step_name_escaped}")')
+                    else:
+                        # Regular run steps get standard rectangle
+                        lines.append(f'        {step_id}["{step_name_escaped}"]')
+
+                    # Link to previous step
+                    if prev_step_id:
+                        lines.append(f"        {prev_step_id} --> {step_id}")
+
+                    prev_step_id = step_id
+
+                # Track first and last step nodes for job dependencies
+                first_step_idx, _ = named_steps[0]
+                last_step_idx, _ = named_steps[-1]
+                first_step_id = f"{job_id_safe}_step_{first_step_idx}"
+                last_step_id = f"{job_id_safe}_step_{last_step_idx}"
+                job_start_nodes[job.id] = first_step_id
+                job_end_nodes[job.id] = last_step_id
+            else:
+                # Job with no named steps - create a single placeholder node
+                placeholder_id = f"{job_id_safe}_placeholder"
+                lines.append(f"        {placeholder_id}[No named steps defined]")
+                job_start_nodes[job.id] = placeholder_id
+                job_end_nodes[job.id] = placeholder_id
+        else:
+            # Job with no steps - create a single node
+            placeholder_id = f"{job_id_safe}_placeholder"
+            lines.append(f"        {placeholder_id}[No steps defined]")
+            job_start_nodes[job.id] = placeholder_id
+            job_end_nodes[job.id] = placeholder_id
+
+        lines.append("    end")
+
+    # Add job dependencies
+    for job in workflow.jobs.values():
+        for needed_job_id in job.needs:
+            needed_job = workflow.jobs[needed_job_id]
+            lines.append(f"    {needed_job.mermaid_id} -.-> {job.mermaid_id}")
+
+    return "\n".join(lines)

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.0}/src/mkdocstrings_handlers/github/templates/material/workflow.html.jinja

@@ -74,6 +74,17 @@ Context:
     {% endif %}
   {% endblock description %}
 
+  {% block flowchart scoped %}
+    {% if options.workflow_chart %}
+      {% set flowchart = data | generate_mermaid_flowchart(options.workflow_chart_step_direction) %}
+      {% if flowchart %}
+        <pre class="mermaid"><code>
+        {{ flowchart }}
+        </code></pre>
+      {% endif %}
+    {% endif %}
+  {% endblock flowchart %}
+
   {% block inputs scoped %}
     {% if options.show_inputs %}
       {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=options.show_inputs_only_required) %}