mkdocstrings-github 0.7.2__py3-none-any.whl → 0.8.0__py3-none-any.whl

{mkdocstrings_github-0.7.2.dist-info → mkdocstrings_github-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-github
-Version: 0.7.2
+Version: 0.8.0
 Summary: A GitHub Action handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -23,6 +23,7 @@ Classifier: Typing :: Typed
 Requires-Python: <3.15,>=3.10
 Requires-Dist: gitpython<4,>=3.1.45
 Requires-Dist: mkdocstrings<2,>=1
+Requires-Dist: ruamel-yaml-clib<1,>=0.2.14
 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.7.2.dist-info → mkdocstrings_github-0.8.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
 mkdocstrings_handlers/github/__init__.py,sha256=0WdFUIq4Xu2ZFtlZNIYCQSoqcx3Ot9Wv41_X_dwbFww,248
-mkdocstrings_handlers/github/config.py,sha256=G__jcRZkhltdwwh1YJWbx9xEdblF9mTc4_L1NEWE6Bw,7873
-mkdocstrings_handlers/github/handler.py,sha256=xRT_GEcbcko5sqtj3eLqsPW2cFsLY4xImw-_K-GhwLE,8966
+mkdocstrings_handlers/github/config.py,sha256=iUgoIFoICXpIk7RPEGjLLTuLnG-BvcOknH1o2rsSvwA,8274
+mkdocstrings_handlers/github/handler.py,sha256=mDmXhLrkNFGln9bDODnLN9UuZJXJsoNDkwjSiWQQU4o,9248
 mkdocstrings_handlers/github/objects.py,sha256=2gKgrkkyBem3a0MUpffAH5C5asLk8Dqgqf6ntZuTxCo,9317
 mkdocstrings_handlers/github/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/github/rendering.py,sha256=N92Gbm9Qi4I2EZC69JsEixO1AdHuf1du9isJNXG4vhQ,7192
+mkdocstrings_handlers/github/rendering.py,sha256=Ef4WxnE6bqb20-QjGwKcvSXceebGGPtME1OiTFXLqM4,8408
 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/action.html.jinja,sha256=unNZDj_E7MbjNvGY4FMq3aRFpYNp-LCnio6Cca4dgI4,3019
 mkdocstrings_handlers/github/templates/material/heading.html.jinja,sha256=wnvZpNED8Dhb935qnddeDExXN-MIUz8frRRfgq-A9VA,1396
 mkdocstrings_handlers/github/templates/material/inputs.html.jinja,sha256=UE8RmfMlF6np7CP-920CwgkbXIcKNgl9KgK1BJ588GM,3271
 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=VS3AqT0OgX6QPFCwN63tULM9tC4t6FGtOoVCixQGPl4,4543
-mkdocstrings_github-0.7.2.dist-info/METADATA,sha256=7CijK_TVAy9PTsCLWHYFo_rlUoa2Tqk-ufoQXlc90qg,4052
-mkdocstrings_github-0.7.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mkdocstrings_github-0.7.2.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
-mkdocstrings_github-0.7.2.dist-info/RECORD,,
+mkdocstrings_handlers/github/templates/material/workflow.html.jinja,sha256=lTdssopSZVvEeenNIzD9zKYhLts7nk8kgWYaIuzPTrE,4698
+mkdocstrings_github-0.8.0.dist-info/METADATA,sha256=xnzS9p-rgldre9eokEDG0rvIa458XeH7tC5-OsR0rRE,4095
+mkdocstrings_github-0.8.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mkdocstrings_github-0.8.0.dist-info/licenses/LICENSE,sha256=5enZtJ4zSp0Ps3jTqFQ4kadcx62BhgTaDNPrXWb3g3E,1069
+mkdocstrings_github-0.8.0.dist-info/RECORD,,

{mkdocstrings_github-0.7.2.dist-info → mkdocstrings_github-0.8.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.28.0
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

mkdocstrings_handlers/github/config.py

@@ -127,6 +127,21 @@ class GitHubOptions(BaseModel):
         description="The version string to use if [`signature_version`][mkdocstrings_handlers.github.config.GitHubOptions.signature_version] is set to `string`.",
     )
 
+    signature_prematter: str = Field(
+        default="",
+        description="Text to render before the signature code block.",
+    )
+
+    signature_indent: int = Field(
+        default=0,
+        description="Number of spaces to indent the signature by.",
+    )
+
+    signature_postmatter: str = Field(
+        default="",
+        description="Text to render after the signature code block.",
+    )
+
     # Parameter options
     show_inputs: bool = Field(
         default=True,

mkdocstrings_handlers/github/handler.py

@@ -168,16 +168,18 @@ class GitHubHandler(BaseHandler):
         self.env.lstrip_blocks = True
         self.env.keep_trailing_newline = False
         self.env.filters["format_action_signature"] = rendering.format_action_signature
+        self.env.filters["indent_text"] = rendering.indent_text
+        self.env.filters["wrap_signature_block"] = rendering.wrap_signature_block
         self.env.filters["order_parameters"] = rendering.order_parameters
         self.env.filters["filter_parameters"] = rendering.filter_parameters
         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
-        self.env.globals["repository_name"] = self.get_repository_name()
+        self.env.globals["semver_tag"] = self.semver  # ty: ignore[invalid-assignment]
+        self.env.globals["major_tag"] = self.major  # ty: ignore[invalid-assignment]
+        self.env.globals["git_repo"] = self.repo  # ty: ignore[invalid-assignment]
+        self.env.globals["repository_name"] = self.get_repository_name()  # ty: ignore[invalid-assignment]
 
     def collect(self, identifier: str, options: GitHubOptions) -> Workflow | Action | None:
         working_tree_dir = self.repo.working_tree_dir

mkdocstrings_handlers/github/rendering.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import textwrap
 from collections import OrderedDict
 from typing import TYPE_CHECKING, Sequence
 
@@ -41,6 +42,48 @@ def format_action_signature(context: Context, id: str, repo: str, options: GitHu
     return f"{name}@{version}"
 
 
+def indent_text(text: str, indent: int) -> str:
+    """Indent every line of a block of text by a given number of spaces.
+
+    Args:
+        text: The text to indent.
+        indent: Number of spaces to indent by. Negative values are treated as 0.
+
+    Returns:
+        The indented text.
+    """
+    if indent <= 0:
+        return text
+    prefix = " " * indent
+    return "\n".join(prefix + line if line else line for line in text.split("\n"))
+
+
+def wrap_signature_block(
+    body: str,
+    indent: int = 0,
+    prematter: str = "",
+    postmatter: str = "",
+) -> str:
+    """Wrap a signature body with optional indentation and surrounding matter.
+
+    Args:
+        body: The signature body.
+        indent: Number of spaces to indent the body by.
+        prematter: Text to render before the body.
+        postmatter: Text to render after the body.
+
+    Returns:
+        The formatted signature block.
+    """
+    body = textwrap.dedent(body)
+    body = indent_text(body, indent)
+    if prematter and not prematter.endswith("\n"):
+        prematter += "\n"
+    if postmatter and not postmatter.startswith("\n"):
+        postmatter = "\n" + postmatter
+    return f"{prematter}{body}{postmatter}"
+
+
 def group_parameters(
     parameters: Sequence[Input | Output | Secret],
     do_group: bool,

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

@@ -29,6 +29,7 @@ Context:
       {% with inputs = data.inputs | order_parameters(options.parameters_order) | filter_parameters(required=True) %}
         <div class="annotate">
         {% filter highlight(language="yaml", inline=False, linenums=False) %}
+          {% filter wrap_signature_block(options.signature_indent, options.signature_prematter, options.signature_postmatter) %}
           - uses: {{ signature }}
           {% if inputs|length > 0 %}
             with:
@@ -36,6 +37,7 @@ Context:
               {{ input.name }}: ({{ loop.index }})
               {% endfor %}
           {% endif %}
+          {% endfilter %}
         {% endfilter %}
         </div>
         <ol>

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

@@ -27,6 +27,7 @@ Context:
       {% 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) %}
+          {% filter wrap_signature_block(options.signature_indent, options.signature_prematter, options.signature_postmatter) %}
           uses: {{ signature }}
           {% if options.signature_show_permissions and data.permissions|length > 0 %}
           {% if data.permission_read_all %}
@@ -54,6 +55,7 @@ Context:
             {% endfor %}
           {% endif %}
           {% endif %}
+          {% endfilter %}
         {% endfilter %}
         </div>
         <ol>