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

mkdocstrings_github-0.7.1/.github/workflows/docs.yaml

@@ -0,0 +1,55 @@
+name: Docs
+
+# Controls when the workflow will run
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: >-
+          The ref to checkout and use to create docs
+        type: string
+        default: ""
+      push:
+        description: >-
+          Push the documentation to the remote branch
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Required to push to the documentation branch
+          ref: ${{ inputs.ref }} 
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+  
+      - name: Sync dependencies
+        run: |
+          uv sync --no-dev --group docs
+
+      - name: Build documentation
+        run: |
+          uv run zensical build --clean
+        
+      - uses: actions/upload-pages-artifact@v4
+        if: ${{ inputs.push }}
+        with:
+          path: site
+
+      - uses: actions/deploy-pages@v4
+        if: ${{ inputs.push }}
+        id: deployment

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.1}/.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@v6
           
-      - 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.1}/.github/workflows/qualify.yaml

@@ -24,12 +24,11 @@ jobs:
     name: Test deploy documentation
     uses: ./.github/workflows/docs.yaml
     permissions: 
-      contents: write
+      contents: read
+      pages: write
+      id-token: write
     secrets: inherit
     with:
-      version: ${{ format('pr-{0}', github.head_ref) || 'test' }}
-      alias: "test"
-      set-default: false
       push: false
 
   setup:

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.1}/.github/workflows/release.yaml

@@ -153,11 +153,10 @@ jobs:
     if: github.event.pull_request.merged
     uses: ./.github/workflows/docs.yaml
     permissions:
-      contents: write
+      contents: read
+      pages: write
+      id-token: write
     secrets: inherit
     with:
-      version: ${{ needs.release.outputs.next-tag || needs.release.outputs.last-tag }}
-      alias: latest
-      set-default: true
       ref: ${{ needs.release.outputs.next-tag }}
       push: true

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.1}/.pre-commit-config.yaml

@@ -7,7 +7,7 @@ repos:
       - id: check-merge-conflict
 
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.24.1
+    rev: v0.25
     hooks:
       - id: validate-pyproject
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.6.4
+Version: 0.7.1
 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.1}/docs/changelog.md

@@ -2,6 +2,48 @@
 
 <!-- version list -->
 
+## v0.7.1 (2026-02-03)
+
+### Bug Fixes
+
+- Build with zensical ([#51](https://github.com/watermarkhu/mkdocstrings-github/pull/51),
+  [`da116f2`](https://github.com/watermarkhu/mkdocstrings-github/commit/da116f20d0c7eaef694a863542450dd313ca85bd))
+
+### Build System
+
+- **deps**: Update dependency ruff to ~=0.15.0
+  ([#52](https://github.com/watermarkhu/mkdocstrings-github/pull/52),
+  [`7e20a99`](https://github.com/watermarkhu/mkdocstrings-github/commit/7e20a99bee878c598385d79b902bc9a9b59924cb))
+
+- **deps**: Update pre-commit hook abravalheri/validate-pyproject to v0.25
+  ([#50](https://github.com/watermarkhu/mkdocstrings-github/pull/50),
+  [`840303e`](https://github.com/watermarkhu/mkdocstrings-github/commit/840303e040c241645b0d86ebc9ed3668aba1ea6e))
+
+### Continuous Integration
+
+- **deps**: Update actions/checkout action to v6
+  ([#49](https://github.com/watermarkhu/mkdocstrings-github/pull/49),
+  [`60860d7`](https://github.com/watermarkhu/mkdocstrings-github/commit/60860d7c03ba10c75959219c96faf8e2906586d5))
+
+### Documentation
+
+- Build with zensical ([#51](https://github.com/watermarkhu/mkdocstrings-github/pull/51),
+  [`da116f2`](https://github.com/watermarkhu/mkdocstrings-github/commit/da116f20d0c7eaef694a863542450dd313ca85bd))
+
+
+## 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.1/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.1}/docs/usage/index.md

@@ -18,7 +18,7 @@
 
 ## Installation
 
-This package is extension package to [*mkdocstrings*](https://mkdocstrings.github.io/), a framework for auto-documentation for various languages. Language support is inserted into the framework by providing *handlers*. The *mkdocstrings-github* package provides a GitHub handler.
+This package is an extension for [*mkdocstrings*](https://mkdocstrings.github.io/), a framework for auto-documentation within [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) or [Zensical](https://zensical.org/about/). Language support is inserted into the framework by providing *handlers*. The *mkdocstrings-github* package provides a GitHub handler.
 
 --8<-- "README.md:install"
 

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.1}/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
@@ -35,7 +35,6 @@ nav:
 - mkdocstrings: https://mkdocstrings.github.io/
 
 theme:
-  name: material
   logo: img/logo.png
   favicon: favicon.png
   custom_dir: docs/overrides
@@ -99,13 +98,13 @@ markdown_extensions:
     pygments_lang_class: true
 - pymdownx.magiclink
 - pymdownx.snippets:
-    base_path: [!relative $config_dir]
+    base_path: .
     check_paths: true
 - pymdownx.superfences:
     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 +120,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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-github"
-version = "0.6.4"
+version = "0.7.1"
 description = "A GitHub Action handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
@@ -36,7 +36,7 @@ dependencies = [
 [dependency-groups]
 dev = [
     "ty~=0.0.11",
-    "ruff~=0.14.0",
+    "ruff~=0.15.0",
     "prek>=0.2.1",
     "pydantic~=2.12",
     "pytest~=9.0.0",
@@ -46,13 +46,14 @@ dev = [
     "python-semantic-release~=10.5.0",
 ]
 docs = [
-    "mkdocs-material~=9.5",
     "mkdocs-callouts~=1.15",
     "mkdocs-git-revision-date-localized-plugin~=1.3",
     "mkdocs-minify-plugin~=0.8",
     "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",
+    "zensical>=0.0.15",
 ]
 
 

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.1}/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.1}/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
@@ -235,11 +236,15 @@ def get_handler(
     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)
+    if tool_config.config_file_path is None:
+        root = Path.cwd()
+    else:
+        root = Path(tool_config.config_file_path).parent
+    repo = git.Repo(path=root, search_parent_directories=True)
+    config = GitHubConfig(**handler_config)
 
     return GitHubHandler(
-        config=GitHubConfig(**handler_config),
+        config=config,
         repo=repo,
         **kwargs,
     )

{mkdocstrings_github-0.6.4 → mkdocstrings_github-0.7.1}/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