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

{mkdocstrings_github-0.6.0 → mkdocstrings_github-0.6.2}/.github/workflows/docs.yaml

@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # Required to push to the documentation branch
           ref: ${{ inputs.ref }} 

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

@@ -40,7 +40,7 @@ jobs:
       python-versions: ${{ steps.get-versions.outputs.python-versions }}
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
     
     - name: Get Python versions from pyproject.toml
       id: get-versions
@@ -65,7 +65,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
       with:
         submodules: true
 
@@ -143,7 +143,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 2
 

{mkdocstrings_github-0.6.0 → mkdocstrings_github-0.6.2}/.github/workflows/release.yaml

@@ -39,7 +39,7 @@ jobs:
         git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
 
     - name: Checkout repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
       with:
         fetch-depth: 0
         ref: ${{ github.sha }}
@@ -123,7 +123,7 @@ jobs:
       id-token: write
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
       with:
         ref: ${{ needs.release.outputs.next-tag }}
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.6.0
+Version: 0.6.2
 Summary: A GitHub Action handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -22,7 +22,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Requires-Dist: gitpython<4,>=3.1.45
-Requires-Dist: mkdocstrings<1,>=0.29
+Requires-Dist: mkdocstrings<2,>=1
 Requires-Dist: ruamel-yaml<1,>=0.18.16
 Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
 Description-Content-Type: text/markdown

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

@@ -2,6 +2,57 @@
 
 <!-- version list -->
 
+## v0.6.2 (2025-11-30)
+
+### Chores
+
+- **deps**: Update group-pyproject
+  ([#45](https://github.com/watermarkhu/mkdocstrings-github/pull/45),
+  [`5b13468`](https://github.com/watermarkhu/mkdocstrings-github/commit/5b1346847e9e9347ee8d9cbd84d62d23c1c82223))
+
+- **deps**: Update group-pyproject (major)
+  ([#45](https://github.com/watermarkhu/mkdocstrings-github/pull/45),
+  [`5b13468`](https://github.com/watermarkhu/mkdocstrings-github/commit/5b1346847e9e9347ee8d9cbd84d62d23c1c82223))
+
+### Continuous Integration
+
+- **deps**: Update actions/checkout action to v6
+  ([#44](https://github.com/watermarkhu/mkdocstrings-github/pull/44),
+  [`738ef72`](https://github.com/watermarkhu/mkdocstrings-github/commit/738ef727a737de1851fb4ecd556f5f4cf6c6d667))
+
+
+## v0.6.1 (2025-11-10)
+
+### Build System
+
+- **deps**: Update dependency inline-snapshot to ~=0.31.0
+  ([#38](https://github.com/watermarkhu/mkdocstrings-github/pull/38),
+  [`df160a0`](https://github.com/watermarkhu/mkdocstrings-github/commit/df160a0f10f19d0ac589d2a4e13d9260d4b93fe0))
+
+- **deps**: Update dependency pytest to v9
+  ([#40](https://github.com/watermarkhu/mkdocstrings-github/pull/40),
+  [`f338dbc`](https://github.com/watermarkhu/mkdocstrings-github/commit/f338dbcbf70dd89a1559ead510896816a0ed1ce0))
+
+- **deps**: Update dependency python-semantic-release to ~=10.5.0
+  ([#41](https://github.com/watermarkhu/mkdocstrings-github/pull/41),
+  [`e1a78c7`](https://github.com/watermarkhu/mkdocstrings-github/commit/e1a78c753faa67b937737fc22e4826ba609bcc70))
+
+### Chores
+
+- **deps**: Update dependency mkdocstrings-python to ~=1.19.0
+  ([#42](https://github.com/watermarkhu/mkdocstrings-github/pull/42),
+  [`7f92d5d`](https://github.com/watermarkhu/mkdocstrings-github/commit/7f92d5d0613007a7f1cc0cde76ba2159d8f30efd))
+
+### Testing
+
+- Fix test_get_repository_name_no_remotes for CI environment
+  ([#39](https://github.com/watermarkhu/mkdocstrings-github/pull/39),
+  [`a04e7c7`](https://github.com/watermarkhu/mkdocstrings-github/commit/a04e7c78b7b2caf91b48f8d257b84c3e3e549bf3))
+
+- Improve test coverage to 99% ([#39](https://github.com/watermarkhu/mkdocstrings-github/pull/39),
+  [`a04e7c7`](https://github.com/watermarkhu/mkdocstrings-github/commit/a04e7c78b7b2caf91b48f8d257b84c3e3e549bf3))
+
+
 ## v0.6.0 (2025-10-27)
 
 ### Build System

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

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocstrings-github"
-version = "0.6.0"
+version = "0.6.2"
 description = "A GitHub Action handler for mkdocstrings"
 authors = [
     { name = "Mark Hu", email = "watermarkhu@gmail.com" }
@@ -28,29 +28,29 @@ classifiers = [
 
 dependencies = [
     "gitpython>=3.1.45,<4",
-    "mkdocstrings>=0.29,<1",
+    "mkdocstrings>=1,<2",
     "ruamel.yaml>=0.18.16,<1",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
 
 [dependency-groups]
 dev = [
-    "ty~=0.0.1a22",
+    "ty~=0.0.1a29",
     "ruff~=0.14.0",
     "prek>=0.2.1",
     "pydantic~=2.12",
-    "pytest~=8.4.1",
+    "pytest~=9.0.0",
     "pytest-cov~=7.0.0",
     "beautifulsoup4>=4.13.3",
-    "inline-snapshot~=0.30.0",
-    "python-semantic-release~=10.4.1",
+    "inline-snapshot~=0.31.0",
+    "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~=1.18.2",
+    "mkdocstrings-python~=2.0.0",
     "mike~=2.1",
     "griffe-pydantic~=1.1.7",
 ]

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

@@ -179,7 +179,10 @@ class GitHubHandler(BaseHandler):
         self.env.globals["repository_name"] = self.get_repository_name()
 
     def collect(self, identifier: str, options: GitHubOptions) -> Workflow | Action | None:
-        path = Path(self.repo.working_tree_dir) / identifier
+        working_tree_dir = self.repo.working_tree_dir
+        if working_tree_dir is None:
+            raise CollectionError("Repository working tree directory is not available.")
+        path = Path(working_tree_dir) / identifier
 
         if path.suffix in (".yml", ".yaml"):
             if not path.is_file():
@@ -199,12 +202,15 @@ class GitHubHandler(BaseHandler):
             )
         return data
 
-    def render(self, data: Workflow | Action, options: GitHubOptions) -> str:
+    def render(
+        self, data: Workflow | Action, options: GitHubOptions, *, locale: str | None = None
+    ) -> str:
         """Render a template using provided data and configuration options.
 
         Arguments:
             data: The collected data to render.
             options: The handler's configuration options.
+            locale: The locale to use for rendering (unused in this handler).
 
         Returns:
             The rendered template as HTML.

mkdocstrings_github-0.6.2/test/test_coverage.py

@@ -0,0 +1,382 @@
+"""Tests to improve code coverage for uncovered lines."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import Mock
+
+import pytest
+from mkdocs.exceptions import PluginError
+
+from mkdocstrings_handlers.github.objects import (
+    Input,
+    PermissionLevel,
+    Workflow,
+    _get_member,
+)
+from mkdocstrings_handlers.github.rendering import (
+    anchor_id,
+    as_string,
+    filter_parameters,
+    format_action_signature,
+)
+
+if TYPE_CHECKING:
+    from mkdocstrings_handlers.github import GitHubHandler
+
+
+class TestRendering:
+    """Test rendering module functions."""
+
+    def test_as_string_with_bool_false(self):
+        """Test as_string with boolean False value."""
+        assert as_string(False) == "false"
+
+    def test_as_string_with_bool_true(self):
+        """Test as_string with boolean True value."""
+        assert as_string(True) == "true"
+
+    def test_as_string_with_int(self):
+        """Test as_string with integer value."""
+        assert as_string(42) == "42"
+
+    def test_as_string_with_float(self):
+        """Test as_string with float value."""
+        assert as_string(3.14) == "3.14"
+
+    def test_as_string_with_none(self):
+        """Test as_string with None value."""
+        assert as_string(None) == ""
+
+    def test_as_string_with_string(self):
+        """Test as_string with string value."""
+        assert as_string("test") == "test"
+
+    def test_as_string_with_unsupported_type(self):
+        """Test as_string raises TypeError for unsupported types."""
+        with pytest.raises(TypeError, match="Unsupported type"):
+            as_string([1, 2, 3])  # type: ignore
+
+    def test_filter_parameters_optional(self):
+        """Test filter_parameters with optional filter."""
+        params = [
+            Input(name="required", required=True),
+            Input(name="optional", required=False),
+        ]
+        filtered = filter_parameters(params, optional=True)
+        assert len(filtered) == 1
+        assert filtered[0].name == "optional"
+
+    def test_filter_parameters_description(self):
+        """Test filter_parameters with description filter."""
+        params = [
+            Input(name="with_desc", description="Has description"),
+            Input(name="without_desc", description=""),
+        ]
+        # When description=True, it filters OUT parameters without description
+        # So we keep only parameters WITH description
+        filtered = filter_parameters(params, description=True)
+        assert len(filtered) == 1
+        assert filtered[0].name == "with_desc"
+
+    def test_filter_parameters_default(self):
+        """Test filter_parameters with default filter."""
+        params = [
+            Input(name="with_default", default="value"),
+            Input(name="without_default", default=None),
+        ]
+        # When default=True, it filters OUT parameters without default
+        # So we keep only parameters WITH default
+        filtered = filter_parameters(params, default=True)
+        assert len(filtered) == 1
+        assert filtered[0].name == "with_default"
+
+    def test_anchor_id(self):
+        """Test anchor_id with spaces."""
+        result = anchor_id("my name", "input", "parent id")
+        assert result == "parent-id--input.my-name"
+
+    def test_format_action_signature_non_repo(self):
+        """Test format_action_signature when git_repo is not a Repo instance."""
+        from mkdocstrings_handlers.github.config import GitHubOptions
+
+        # Test with ref version when git_repo is not a Repo
+        context = Mock()
+        context.environment.globals = {"git_repo": "not_a_repo"}
+
+        options = GitHubOptions(signature_version="ref")
+        result = format_action_signature(context, ".", "owner/repo", options)
+        assert result == "owner/repo@unknown"
+
+    def test_format_action_signature_exception_handling(self):
+        """Test format_action_signature when accessing head.ref.name raises exception."""
+        import git
+
+        from mkdocstrings_handlers.github.config import GitHubOptions
+
+        # Create a mock that is a Repo instance but raises exception when accessing head.ref.name
+        context = Mock()
+
+        # Create an actual Repo type mock with side effect
+        mock_repo = Mock(spec=git.Repo)
+        type(mock_repo.head.ref).name = Mock(side_effect=Exception("Test exception"))
+
+        context.environment.globals = {"git_repo": mock_repo}
+
+        options = GitHubOptions(signature_version="ref")
+        result = format_action_signature(context, ".", "owner/repo", options)
+        assert result == "owner/repo@unknown"
+
+
+class TestObjects:
+    """Test objects module functions and classes."""
+
+    def test_get_member_raises_key_error(self):
+        """Test _get_member raises KeyError when key is missing and no default."""
+        with pytest.raises(KeyError, match="Missing key"):
+            _get_member({}, "missing_key", error_message="Missing key")
+
+    def test_permission_level_from_label_invalid(self):
+        """Test PermissionLevel.from_label raises ValueError for invalid label."""
+        with pytest.raises(ValueError, match="No Permission with label"):
+            PermissionLevel.from_label("invalid")
+
+    def test_permission_level_gt_not_implemented(self):
+        """Test PermissionLevel.__gt__ returns NotImplemented for non-PermissionLevel."""
+        result = PermissionLevel.read.__gt__("string")
+        assert result == NotImplemented
+
+    def test_workflow_from_file_no_workflow_call(self, tmp_path):
+        """Test Workflow.from_file returns None when workflow_call is not present."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  push:
+    branches: [main]
+"""
+        )
+
+        result = Workflow.from_file(workflow_file, "test.yml")
+        assert result is None
+
+    def test_workflow_invalid_permission_level_string(self, tmp_path):
+        """Test Workflow.from_file raises ValueError for invalid permission string."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+permissions: invalid-level
+"""
+        )
+
+        with pytest.raises(ValueError, match="Unknown permission level"):
+            Workflow.from_file(workflow_file, "test.yml")
+
+    def test_workflow_invalid_permission_type(self, tmp_path):
+        """Test Workflow.from_file raises ValueError for invalid permission type."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+permissions: 123
+"""
+        )
+
+        with pytest.raises(ValueError, match="permissions must be a string or a dictionary"):
+            Workflow.from_file(workflow_file, "test.yml")
+
+    def test_workflow_invalid_job_permission_type(self, tmp_path):
+        """Test Workflow.from_file raises ValueError for invalid job permission type."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions: 123
+"""
+        )
+
+        with pytest.raises(ValueError, match="permissions must be a string or a dictionary"):
+            Workflow.from_file(workflow_file, "test.yml")
+
+
+class TestHandler:
+    """Test handler module functions."""
+
+    def test_get_releases_exception_handling(self, handler: GitHubHandler):
+        """Test get_releases handles exception when getting git tags fails."""
+        # Create a mock repo that raises exception when accessing tags
+        mock_repo = Mock()
+        mock_repo.tags = Mock(side_effect=Exception("Git error"))
+
+        # Replace the handler's repo with our mock
+        original_repo = handler.repo
+        original_semver = handler.semver
+        original_major = handler.major
+        handler.repo = mock_repo
+        handler.semver = ""
+        handler.major = ""
+
+        try:
+            # Should handle exception gracefully without raising
+            handler.get_releases()
+            assert handler.semver == ""
+            assert handler.major == ""
+        finally:
+            # Restore original repo and values
+            handler.repo = original_repo
+            handler.semver = original_semver
+            handler.major = original_major
+
+    def test_get_releases_with_invalid_version_tag(self, handler: GitHubHandler, tmp_path):
+        """Test get_releases handles tags with invalid version format."""
+        import git
+
+        # Create a temporary git repo with a commit
+        repo = git.Repo.init(tmp_path)
+
+        # Create a file and commit it so we have a valid HEAD
+        test_file = tmp_path / "test.txt"
+        test_file.write_text("test")
+        repo.index.add([str(test_file)])
+        repo.index.commit("Initial commit")
+
+        # Create tags with invalid version format (including semver-like tags with invalid versions)
+        repo.create_tag("invalid-tag")
+        repo.create_tag("another-invalid")
+        repo.create_tag("v1.2.3")  # Valid semver
+        repo.create_tag("v99.99.99")  # Valid semver
+
+        # Replace the handler's repo with our test repo
+        original_repo = handler.repo
+        original_semver = handler.semver
+        original_major = handler.major
+        handler.repo = repo
+        # Reset values so get_releases starts fresh
+        handler.semver = ""
+        handler.major = ""
+
+        try:
+            handler.get_releases()
+
+            # Should use the latest valid semver tag
+            assert handler.semver == "v99.99.99"
+            # No major tags (v1, v2, etc.) were created, only semver tags
+            assert handler.major == ""
+        finally:
+            # Restore original repo and values
+            handler.repo = original_repo
+            handler.semver = original_semver
+            handler.major = original_major
+
+    def test_get_releases_with_tags_triggering_invalid_version(self, handler: GitHubHandler):
+        """Test get_releases handles tags that trigger InvalidVersion exception."""
+        # Create a mock repo with tags that will trigger InvalidVersion
+        mock_tag1 = Mock()
+        mock_tag1.name = "vinvalid"  # Matches major pattern but invalid version
+
+        mock_tag2 = Mock()
+        mock_tag2.name = "v1"  # Valid major tag
+
+        mock_repo = Mock()
+        mock_repo.tags = [mock_tag1, mock_tag2]
+
+        # Replace the handler's repo with our mock
+        original_repo = handler.repo
+        handler.repo = mock_repo
+
+        try:
+            handler.get_releases()
+
+            # Should gracefully handle the invalid version and use the valid one
+            assert handler.major == "v1"
+        finally:
+            # Restore original repo
+            handler.repo = original_repo
+
+    def test_get_options_invalid(self, handler: GitHubHandler):
+        """Test get_options raises PluginError for invalid options."""
+        with pytest.raises(PluginError, match="Invalid options"):
+            handler.get_options({"invalid_option": "value", "heading_level": "not_an_int"})
+
+    def test_get_repository_name_no_remotes(self, handler: GitHubHandler, tmp_path):
+        """Test get_repository_name raises error when no valid remote is found."""
+        import os
+
+        import git
+
+        # Create a temporary git repo without any remotes
+        repo = git.Repo.init(tmp_path)
+
+        # Replace the handler's repo with our test repo
+        original_repo = handler.repo
+        handler.repo = repo
+
+        # Temporarily clear GITHUB_ACTIONS and GITHUB_REPOSITORY env vars
+        # to ensure the test actually checks the remote URL logic
+        github_actions = os.environ.pop("GITHUB_ACTIONS", None)
+        github_repo = os.environ.pop("GITHUB_REPOSITORY", None)
+
+        try:
+            with pytest.raises(
+                PluginError,
+                match="Could not determine GitHub repository owner/name from any git remote URL",
+            ):
+                handler.get_repository_name()
+        finally:
+            # Restore original repo
+            handler.repo = original_repo
+            # Restore environment variables
+            if github_actions is not None:
+                os.environ["GITHUB_ACTIONS"] = github_actions
+            if github_repo is not None:
+                os.environ["GITHUB_REPOSITORY"] = github_repo
+
+
+class TestWorkflowPermissions:
+    """Test workflow permission handling."""
+
+    def test_workflow_job_permission_string(self, tmp_path):
+        """Test Workflow with job-level permission strings."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions: read-all
+"""
+        )
+
+        workflow = Workflow.from_file(workflow_file, "test.yml")
+        assert workflow is not None
+        assert workflow.permission_read_all
+
+    def test_workflow_job_permission_write_all(self, tmp_path):
+        """Test Workflow with write-all permission."""
+        workflow_file = tmp_path / "workflow.yml"
+        workflow_file.write_text(
+            """
+name: Test Workflow
+on:
+  workflow_call:
+permissions: write-all
+"""
+        )
+
+        workflow = Workflow.from_file(workflow_file, "test.yml")
+        assert workflow is not None
+        assert workflow.permission_write_all

mkdocstrings_github-0.6.2/test/test_signature_ref.py

@@ -0,0 +1,51 @@
+"""Test signature with ref version to improve coverage."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mkdocstrings_handlers.github import GitHubHandler
+
+
+def test_action_signature_with_ref(session_handler: GitHubHandler) -> None:
+    """Test action signature with ref version to cover rendering.py line 29."""
+    from test.helpers import render
+
+    # This will use the actual git repo and access git_repo.head.ref.name
+    html = render(
+        session_handler,
+        ".",
+        {
+            "signature_version": "ref",
+            "show_signature": True,
+            "show_heading": False,
+            "show_description": False,
+            "show_source": False,
+        },
+    )
+
+    # The signature should contain the current branch name (could be HEAD, main, master, etc.)
+    assert "@" in html
+    # Verify we're actually rendering the signature
+    assert "uses:" in html or "@" in html
+
+
+def test_workflow_signature_with_ref(session_handler: GitHubHandler) -> None:
+    """Test workflow signature with ref version."""
+    from test.helpers import render
+
+    html = render(
+        session_handler,
+        ".github/workflows/reusable-workflow.yml",
+        {
+            "signature_version": "ref",
+            "show_signature": True,
+            "show_heading": False,
+            "show_description": False,
+            "show_source": False,
+        },
+    )
+
+    # The signature should contain the current branch name
+    assert "@" in html