mkdocstrings-github 0.6.3__py3-none-any.whl → 0.7.0__py3-none-any.whl

{mkdocstrings_github-0.6.3.dist-info → mkdocstrings_github-0.7.0.dist-info}/METADATA

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

{mkdocstrings_github-0.6.3.dist-info → mkdocstrings_github-0.7.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
 mkdocstrings_handlers/github/__init__.py,sha256=0WdFUIq4Xu2ZFtlZNIYCQSoqcx3Ot9Wv41_X_dwbFww,248
-mkdocstrings_handlers/github/config.py,sha256=r7efiI-vKbVEeD6utrc55h4RP6VIlabqDebhiIIx_ZA,7120
-mkdocstrings_handlers/github/handler.py,sha256=4El8kAupC4np2lwzvvMHi9AyHzeT4D6f8eUJO0RfKxY,8781
-mkdocstrings_handlers/github/objects.py,sha256=0E899mr7SQBPAZ7W4i0aIi5dyXIdfdxOm57vatXst0k,7818
+mkdocstrings_handlers/github/config.py,sha256=G__jcRZkhltdwwh1YJWbx9xEdblF9mTc4_L1NEWE6Bw,7873
+mkdocstrings_handlers/github/handler.py,sha256=W1hkFowofpsToDLzkR0MRV3ClCQckUS2VkSjfOLKYRU,8875
+mkdocstrings_handlers/github/objects.py,sha256=2gKgrkkyBem3a0MUpffAH5C5asLk8Dqgqf6ntZuTxCo,9317
 mkdocstrings_handlers/github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/github/rendering.py,sha256=pFk621Fqp_R6ZS2dJ0zwEEez0Urqpekial6kqKYDag8,3371
+mkdocstrings_handlers/github/rendering.py,sha256=N92Gbm9Qi4I2EZC69JsEixO1AdHuf1du9isJNXG4vhQ,7192
 mkdocstrings_handlers/github/templates/material/_macros.html.jinja,sha256=1TNUgoOIxm-a1S7eiESrW1fYuzXOjrwFqXQSyA4tkkU,1576
 mkdocstrings_handlers/github/templates/material/action.html.jinja,sha256=C7S8I9bjnrEUahyDB7CkFxtakFrr53KE3t3uyczBPzc,2864
 mkdocstrings_handlers/github/templates/material/heading.html.jinja,sha256=wnvZpNED8Dhb935qnddeDExXN-MIUz8frRRfgq-A9VA,1396
@@ -11,8 +11,8 @@ mkdocstrings_handlers/github/templates/material/inputs.html.jinja,sha256=UE8RmfM
 mkdocstrings_handlers/github/templates/material/outputs.html.jinja,sha256=Z9QD1KSALLDS9VEyugWG1BHpLCHTKYEx4TEQkKIoC3M,2693
 mkdocstrings_handlers/github/templates/material/secrets.html.jinja,sha256=jQ_HaG2ivbZTH74pyV4BAFGQu5Vn03kA_vaEbTSABds,2839
 mkdocstrings_handlers/github/templates/material/style.css,sha256=Nfmds-xHtPJ_IzOv5svA7ih5talHDTiQryN_n0DGdZs,1553
-mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=5dLdHRSQyulyFAVCVZAR_pkw-WXxCtM20cj6RS7IH1Q,4206
-mkdocstrings_github-0.6.3.dist-info/METADATA,sha256=mVWkkUIE2BuAbaPFHb1BJKZu85LRdhWedEjuzIWhPeg,4052
-mkdocstrings_github-0.6.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mkdocstrings_github-0.6.3.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
-mkdocstrings_github-0.6.3.dist-info/RECORD,,
+mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=VS3AqT0OgX6QPFCwN63tULM9tC4t6FGtOoVCixQGPl4,4543
+mkdocstrings_github-0.7.0.dist-info/METADATA,sha256=6Tyvq8M9xxX2zLCOEA9-fzgOX_zQlUMln3dvOujSO7g,4052
+mkdocstrings_github-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mkdocstrings_github-0.7.0.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
+mkdocstrings_github-0.7.0.dist-info/RECORD,,

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_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_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_handlers/github/rendering.py

@@ -6,8 +6,8 @@ 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
+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
@@ -106,3 +106,99 @@ def as_string(value: bool | str | int | float | None) -> str:
             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_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) %}