mkdocstrings-github 0.4.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

{mkdocstrings_github-0.4.4.dist-info → mkdocstrings_github-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.4.4
+Version: 0.5.0
 Summary: A GitHub Action handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -33,14 +33,26 @@ Description-Content-Type: text/markdown
 
 <p align="center">A GitHub Actions handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
 
-<p align="center"><img width=300px src="logo.png"></p>
+<!-- --8<-- [end:header] -->
+
+<p align="center"><img width=300px src="docs/img/logo.png"></p>
 
 [![Qualify](https://github.com/watermarkhu/mkdocstrings-github/actions/workflows/qualify.yaml/badge.svg?branch=main)](https://github.com/watermarkhu/mkdocstrings-github/actions/workflows/qualify.yaml)
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://watermarkhu.nl/mkdocstrings-github)
 [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-github.svg)](https://pypi.org/project/mkdocstrings-github/)
 [![codecov](https://codecov.io/github/watermarkhu/mkdocstrings-github/graph/badge.svg?token=M6XW8UeURE)](https://codecov.io/github/watermarkhu/mkdocstrings-github)
 
-<!-- --8<-- [end:header] -->
+
+
+For example, the following page is generated from [actions/checkout](https://github.com/actions/checkout):
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/img/example_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="docs/img/example_light.png">
+  <img alt="Fallback image description" src="docs/img/example_light.png">
+</picture>
+
+
 <!-- --8<-- [start:install] -->
 You can install the GitHub handler by specifying it as a dependency:
 
@@ -49,9 +61,17 @@ You can install the GitHub handler by specifying it as a dependency:
 # adapt to your dependencies manager
 [project]
 dependencies = [
-    "mkdocstrings-github>=0.X.Y",
+    "mkdocstrings-github",
 ]
 ```
+
+after which the generated documentation can be inserted in the markdown page with:
+
+```md
+::: <path-to-action-or-workflow>
+    handler: github
+```
+
 <!-- --8<-- [end:install] -->
 
 <!-- --8<-- [start:footer] -->

{mkdocstrings_github-0.4.4.dist-info → mkdocstrings_github-0.5.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
 mkdocstrings_handlers/github/__init__.py,sha256=0WdFUIq4Xu2ZFtlZNIYCQSoqcx3Ot9Wv41_X_dwbFww,248
-mkdocstrings_handlers/github/config.py,sha256=pSjA6gU-kC_mXQqNIIGOYEOhtX5VzZDT0H1hRFlGaj8,6089
-mkdocstrings_handlers/github/handler.py,sha256=QJbZjRbllUuGs5rY6SLwaII6hsPQnioa_OmauWGL-lU,8495
-mkdocstrings_handlers/github/objects.py,sha256=JDkY7mg_LGlIEwZHP2wSd8ZkB6RVtRsu_JEpwV-PikQ,7069
+mkdocstrings_handlers/github/config.py,sha256=JrI9HK6g-XwXuKFJegfPOpvw-_ZMG0iipSNnEqU0wcw,6105
+mkdocstrings_handlers/github/handler.py,sha256=ShE0EUsWDgonE4LtR3MFPEzCLwvDb2UztrAiXqQs_oc,8415
+mkdocstrings_handlers/github/objects.py,sha256=ckMEEoj3pdLasGHzZMwYY7XdjwbUdHRch07dAzgEHs0,8217
 mkdocstrings_handlers/github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mkdocstrings_handlers/github/rendering.py,sha256=6xcE2WwyTRW_38g7Ek55hlm53EsFFqueazFw12__DyA,2820
-mkdocstrings_handlers/github/templates/material/action.html.jinja,sha256=_mfYFUJfaYtraK-VF2_i2vPafU0QsBIDb3bYHxuXlI8,2510
+mkdocstrings_handlers/github/templates/material/action.html.jinja,sha256=C7S8I9bjnrEUahyDB7CkFxtakFrr53KE3t3uyczBPzc,2864
 mkdocstrings_handlers/github/templates/material/heading.html.jinja,sha256=wnvZpNED8Dhb935qnddeDExXN-MIUz8frRRfgq-A9VA,1396
 mkdocstrings_handlers/github/templates/material/inputs.html.jinja,sha256=CIcw3OBQdCP4e5A4srLu1v3xoOjsedIw1Zh3qxtG0-A,3482
 mkdocstrings_handlers/github/templates/material/outputs.html.jinja,sha256=jlzVF93q5AyJfOiSl3_1VBVL3c6rjmEcS81s3sri5Gg,2670
 mkdocstrings_handlers/github/templates/material/secrets.html.jinja,sha256=1lMJoxjjeiqetVu0mdLKmZ1faYRReeyjiYvYTZESots,2881
 mkdocstrings_handlers/github/templates/material/style.css,sha256=R2hh1RfHwJ6XNT4YQl_txNkNXcPBZJMCBZn5kQEMQ6M,962
-mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=FsUCb91LdWBwOtMpWOLMTVtP44QQSHuxO-HKR4c9Ld4,3444
-mkdocstrings_github-0.4.4.dist-info/METADATA,sha256=CV-IoKbaNQqIsXV6xzyoxV4W4l51Z-q_If7JqFw0m7w,3340
-mkdocstrings_github-0.4.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mkdocstrings_github-0.4.4.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
-mkdocstrings_github-0.4.4.dist-info/RECORD,,
+mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=5dLdHRSQyulyFAVCVZAR_pkw-WXxCtM20cj6RS7IH1Q,4206
+mkdocstrings_github-0.5.0.dist-info/METADATA,sha256=maSQ6Gbg1xgruSrClF-EHllBLo4fy2q5A30XctacPSw,3867
+mkdocstrings_github-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mkdocstrings_github-0.5.0.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
+mkdocstrings_github-0.5.0.dist-info/RECORD,,

mkdocstrings_handlers/github/config.py

@@ -92,6 +92,16 @@ class GitHubOptions(BaseModel):
         description="Whether to show the signature in the documentation.",
     )
 
+    signature_repository: str = Field(
+        default="",
+        description="""The GitHub repository in the format *owner/repo*.
+
+        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(
         default=False,
         description="Whether to show secrets in the signature.",
@@ -171,16 +181,6 @@ class GitHubOptions(BaseModel):
 class GitHubConfig(BaseModel):
     """Configuration options for the GitHub handler."""
 
-    repo: str = Field(
-        default="",
-        description="""The GitHub repository in the format *owner/repo*.
-
-        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.-]+$"),
-    )
-
     feather_icons_source: str = Field(
         default="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js",
         description="""The source URL for Feather icons.

mkdocstrings_handlers/github/handler.py

@@ -70,41 +70,9 @@ class GitHubHandler(BaseHandler):
         self.major: str = ""
         self.semver: str = ""
 
-        # Determine owner and repo name
-        if not self.config.repo:
-            self.get_repo()
-
         if rendering.ENV_MAJOR_TAG not in os.environ or rendering.ENV_SEMVER_TAG not in os.environ:
             self.get_releases()
 
-    def get_repo(self) -> None:
-        # Get repo from environment variable or git remotes.
-        if os.environ.get("GITHUB_ACTIONS") == "true" and (
-            repo := os.environ.get("GITHUB_REPOSITORY")
-        ):
-            self.config.repo = repo
-        else:
-            # Try each remote to find a valid GitHub owner/repo
-            owner = None
-            repo_name = None
-            for remote in self.repo.remotes:
-                for url in remote.urls:
-                    match = re.search(
-                        r"(?P<host>[\w\.-]+)[/:](?P<owner>[^/]+)/(?P<repo>[^/.]+?)(?:\.git)?$",
-                        url,
-                    )
-                    if match:
-                        owner = match.group("owner")
-                        repo_name = match.group("repo")
-                        break
-                if owner and repo_name:
-                    break
-            if not (owner and repo_name):
-                raise PluginError(
-                    f"Could not determine GitHub repository owner/name from config.repo='{self.config.repo}' or any git remote URL."
-                )
-            self.config.repo = f"{owner}/{repo_name}"
-
     def get_releases(self) -> None:
         # Get all tags from the local git repository.
         try:
@@ -167,6 +135,34 @@ class GitHubHandler(BaseHandler):
         except Exception as error:
             raise PluginError(f"Invalid options: {error}") from error
 
+    def get_repository_name(self) -> str:
+        # Get repo from environment variable or git remotes.
+        if os.environ.get("GITHUB_ACTIONS") == "true" and (
+            repo := os.environ.get("GITHUB_REPOSITORY")
+        ):
+            return repo
+        else:
+            # Try each remote to find a valid GitHub owner/repo
+            owner = None
+            repo_name = None
+            for remote in self.repo.remotes:
+                for url in remote.urls:
+                    match = re.search(
+                        r"(?P<host>[\w\.-]+)[/:](?P<owner>[^/]+)/(?P<repo>[^/.]+?)(?:\.git)?$",
+                        url,
+                    )
+                    if match:
+                        owner = match.group("owner")
+                        repo_name = match.group("repo")
+                        break
+                if owner and repo_name:
+                    break
+            if not (owner and repo_name):
+                raise PluginError(
+                    "Could not determine GitHub repository owner/name from any git remote URL."
+                )
+            return f"{owner}/{repo_name}"
+
     def update_env(self, config: Any) -> None:
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True
@@ -179,6 +175,7 @@ class GitHubHandler(BaseHandler):
         self.env.globals["semver_tag"] = self.semver
         self.env.globals["major_tag"] = self.major
         self.env.globals["git_repo"] = self.repo
+        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

mkdocstrings_handlers/github/objects.py

@@ -106,10 +106,6 @@ class Action:
     branding: dict = field(default_factory=dict)
     template: Literal["action.html.jinja"] = "action.html.jinja"
 
-    @property
-    def members(self) -> list[Input | Output]:
-        return self.inputs + self.outputs
-
     @staticmethod
     def from_file(file: PathLike, id: str) -> "Action":
         source, data = _read_file(file)
@@ -131,6 +127,25 @@ class Action:
         return action
 
 
+# https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions
+PERMISSION_SCOPES: list[str] = [
+    "actions",
+    "attestations",
+    "checks",
+    "contents",
+    "deployments",
+    "discussions",
+    "id-token",
+    "issues",
+    "models",
+    "packages",
+    "pages",
+    "pull-requests",
+    "security-events",
+    "statuses",
+]
+
+
 class PermissionLevel(Enum):
     none = ("none", 0)
     read = ("read", 1)
@@ -151,21 +166,6 @@ class PermissionLevel(Enum):
                 return perm
         raise ValueError(f"No Permission with label '{label}'")
 
-    def __le__(self, other):
-        if isinstance(other, PermissionLevel):
-            return self.number <= other.number
-        return NotImplemented
-
-    def __lt__(self, other):
-        if isinstance(other, PermissionLevel):
-            return self.number < other.number
-        return NotImplemented
-
-    def __ge__(self, other):
-        if isinstance(other, PermissionLevel):
-            return self.number >= other.number
-        return NotImplemented
-
     def __gt__(self, other):
         if isinstance(other, PermissionLevel):
             return self.number > other.number
@@ -187,8 +187,18 @@ class Workflow:
     template: Literal["workflow.html.jinja"] = "workflow.html.jinja"
 
     @property
-    def members(self) -> list[Input | Output | Secret]:
-        return self.inputs + self.outputs + self.secrets
+    def permission_read_all(self) -> bool:
+        return all(
+            scope in self.permissions and self.permissions[scope] == PermissionLevel.read
+            for scope in PERMISSION_SCOPES
+        )
+
+    @property
+    def permission_write_all(self) -> bool:
+        return all(
+            scope in self.permissions and self.permissions[scope] == PermissionLevel.write
+            for scope in PERMISSION_SCOPES
+        )
 
     @staticmethod
     def from_file(file: PathLike, id: str) -> "Workflow | None":
@@ -213,13 +223,36 @@ class Workflow:
                 workflow.outputs.append(Output.from_data(key, **value))
             for key, value in call.get("secrets", {}).items():
                 workflow.secrets.append(Secret.from_data(key, **value))
-        for key, label in data.get("permissions", {}).items():
-            workflow.permissions[key] = PermissionLevel.from_label(label)
+
+        def set_all_permissions(level: str):
+            if level == "read-all":
+                for key in PERMISSION_SCOPES:
+                    workflow.permissions[key] = PermissionLevel.read
+            elif level == "write-all":
+                for key in PERMISSION_SCOPES:
+                    workflow.permissions[key] = PermissionLevel.write
+            else:
+                raise ValueError(f"Unknown permission level '{level}'")
+
+        if isinstance(permissions := data.get("permissions", {}), str):
+            set_all_permissions(permissions)
+        elif isinstance(permissions, dict):
+            for key, label in permissions.items():
+                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():
-            for key, label in job.get("permissions", {}).items():
-                if key in workflow.permissions:
-                    if permission := PermissionLevel.from_label(label) > workflow.permissions[key]:
-                        workflow.permissions[key] = permission
-                else:
-                    workflow.permissions[key] = PermissionLevel.from_label(label)
+            if isinstance(permissions := job.get("permissions", {}), str):
+                set_all_permissions(permissions)
+            elif isinstance(permissions, dict):
+                for key, label in job.get("permissions", {}).items():
+                    if key in workflow.permissions:
+                        permission = PermissionLevel.from_label(label)
+                        if permission > workflow.permissions[key]:
+                            workflow.permissions[key] = permission
+                    else:
+                        workflow.permissions[key] = PermissionLevel.from_label(label)
+            else:
+                raise ValueError("permissions must be a string or a dictionary")
+
         return workflow

mkdocstrings_handlers/github/templates/material/action.html.jinja

@@ -7,7 +7,6 @@ Context:
   config (mkdocstrings_handlers.github.config.GitHubConfig): The global configuration
   options (dict): The local options
 -#}
-
 {% block logs scoped %}
   {#- Logging block.
 
@@ -23,24 +22,30 @@ Context:
 
   {% include "heading.html.jinja" with context %}
 
-  {% set signature = data.id | format_action_signature(config.repo, options) %}
+  {% set signature = data.id | format_action_signature(options.signature_repository if options.signature_repository else repository_name, options) %}
 
   {% block signature scoped %}
     {% if options.show_signature %}
-      {% filter highlight(language="yaml", inline=False, linenums=False) %}
-        - uses: {{ signature }}
-        {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
-        {% if inputs|length > 0 %}
-          with:
-            {% for input in inputs %}
-            {{ input.name }}: 📝
-            {% endfor %}
-        {% endif %}
-        {% endwith %}
-      {% endfilter %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+        <div class="annotate">
+        {% filter highlight(language="yaml", inline=False, linenums=False) %}
+          - uses: {{ signature }}
+          {% if inputs|length > 0 %}
+            with:
+              {% for input in inputs %}
+              {{ input.name }}: ({{ loop.index }})
+              {% endfor %}
+          {% endif %}
+        {% endfilter %}
+        </div>
+        <ol>
+        {% for input in inputs %}
+          <li>{{ input.description | convert_markdown(options.heading_level) if input.description else "(no description)" }}</li>
+        {% endfor %}
+        </ol>
+      {% endwith %}
     {% endif %}
   {% endblock signature %}
-
   {% block description scoped %}
     {% if options.show_description %}
       {{ options.description if options.description else data.description | convert_markdown(options.heading_level, data.id) }}

mkdocstrings_handlers/github/templates/material/workflow.html.jinja

@@ -20,37 +20,51 @@ Context:
 <div class="doc doc-object doc-workflow">
   {% include "heading.html.jinja" with context %}
 
-  {% set signature = data.id | format_action_signature(config.repo, options) %}
+  {% set signature = data.id | format_action_signature(options.signature_repository if options.signature_repository else repository_name, options) %}
 
   {% block signature scoped %}
     {% if options.show_signature %}
-      {% filter highlight(language="yaml", inline=False, linenums=False) %}
-        uses: {{ signature }}
-        {% if options.signature_show_permissions and data.permissions|length > 0 %}
-        permissions:
-          {% for scope, level in data.permissions | items %}
-          {{ scope }}: {{ level.label }}
-          {% endfor %}
-        {% endif %}
-        {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
-        {% if inputs|length > 0 %}
-        with:
-          {% for input in inputs %}
-          {{ input.name }}: 📝
-          {% endfor %}
-        {% endif %}
-        {% endwith %}
-        {% if options.signature_show_secrets %}
-        {% with secrets = data.secrets | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
-        {% if secrets|length > 0 %}
-        secrets:
-          {% for secret in secrets %}
-          {{ secret.name }}: 📝
-          {% endfor %}
-        {% endif %}
-        {% endwith %}
-        {% endif %}
-      {% endfilter %}
+      {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True), secrets = data.secrets | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
+        <div class="annotate">
+        {% filter highlight(language="yaml", inline=False, linenums=False) %}
+          uses: {{ signature }}
+          {% if options.signature_show_permissions and data.permissions|length > 0 %}
+          {% if data.permission_read_all %}
+          permissions: read-all
+          {% elif data.permission_write_all %}
+          permissions: write-all
+          {% else %}
+          permissions:
+            {% for scope, level in data.permissions | items %}
+            {{ scope }}: {{ level.label }}
+            {% endfor %}
+          {% endif %}
+          {% endif %}
+          {% if inputs|length > 0 %}
+          with:
+            {% for input in inputs %}
+            {{ input.name }}: ({{ loop.index }})
+            {% endfor %}
+          {% endif %}
+          {% if options.signature_show_secrets %}
+          {% if secrets|length > 0 %}
+          secrets:
+            {% for secret in secrets %}
+            {{ secret.name }}: ({{ inputs|length + loop.index }})
+            {% endfor %}
+          {% endif %}
+          {% endif %}
+        {% endfilter %}
+        </div>
+        <ol>
+        {% for input in inputs %}
+          <li>{{ input.description | convert_markdown(options.heading_level) if input.description else "(no description)" }}</li>
+        {% endfor %}
+        {% for secret in secrets %}
+          <li>{{ secret.description | convert_markdown(options.heading_level) if secret.description else "(no description)" }}</li>
+        {% endfor %}
+        </ol>
+      {% endwith %}
     {% endif %}
   {% endblock signature %}