mkdocstrings-matlab 2.1.1__tar.gz → 2.1.3__tar.gz

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/.github/CONTRIBUTING.md

@@ -34,7 +34,7 @@ See: [pytest documentation](https://docs.pytest.org/en/stable/)
 
 ## 4. Pull Request Guidelines
 
-- Pull requests should target the `main` branch.
+- Pull requests should target the `dev` branch.
 - Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.
 
 See: [Conventional Commits Spec](https://www.conventionalcommits.org/en/v1.0.0/)

mkdocstrings_matlab-2.1.3/.github/workflows/dev-branch.yaml

@@ -0,0 +1,76 @@
+name: Dev branch
+
+on:
+  # Manually (re)bootstrap the dev branch.
+  workflow_dispatch:
+  # Recreate dev once its pull request into main has been merged.
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  sync-dev:
+    name: Recreate dev branch and draft pull request
+    # Run on manual dispatch, or when a dev -> main pull request was merged.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.pull_request.merged == true &&
+       github.event.pull_request.head.ref == 'dev')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v7
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Recreate dev from main
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Ensure the old dev branch is gone (it may already be
+          # auto-deleted by GitHub when the pull request was merged).
+          git push origin --delete dev || echo "dev branch already deleted."
+
+          # Start a fresh dev branch from main. The empty commit makes dev
+          # diverge from main so a pull request can be opened immediately.
+          git checkout -B dev origin/main
+          git commit --allow-empty -m "chore: bootstrap dev branch"
+          git push --force origin dev
+
+      - name: Create draft pull request
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          open_prs=$(gh pr list --base main --head dev --state open --json number --jq 'length')
+          if [ "$open_prs" -gt 0 ]; then
+            echo "An open dev -> main pull request already exists; skipping creation."
+            exit 0
+          fi
+
+          gh pr create \
+            --base main \
+            --head dev \
+            --draft \
+            --title "chore: merge dev into main" \
+            --body "$(cat <<'EOF'
+          This is the rolling pull request for the `dev` branch.
+
+          Contributor pull requests should target `dev` (see [CONTRIBUTING.md](../blob/main/.github/CONTRIBUTING.md)).
+          Mark this pull request as ready for review and merge it when the changes on
+          `dev` are ready to land on `main`.
+
+          > This pull request is created automatically. Edit the title to follow
+          > [Conventional Commits](https://www.conventionalcommits.org) so the
+          > correct version bump is determined when it is merged.
+          EOF
+          )"

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/.github/workflows/docs.yaml

@@ -38,7 +38,7 @@ jobs:
           ref: ${{ inputs.ref }}
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@v10.0.1
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           version: "latest"
 

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/.github/workflows/qualify.yaml

@@ -13,7 +13,7 @@ on:
       - labeled
       - unlabeled
       - edited
-    branches: [main]
+    branches: [main, dev]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
@@ -73,7 +73,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@v10.0.1
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           version: "latest"
 

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/.github/workflows/release.yaml

@@ -49,7 +49,7 @@ jobs:
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
 
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@v10.0.1
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           version: "latest"
 

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/.gitignore

@@ -122,7 +122,6 @@ celerybeat.pid
 *.sage.py
 
 # Environments
-uv.lock
 .env
 .venv
 env/
@@ -141,6 +140,9 @@ venv.bak/
 # mkdocs documentation
 /site
 
+# inline-snapshot
+test/snapshots/files_using_external.txt
+
 # mypy
 .mypy_cache/
 .dmypy.json

mkdocstrings_matlab-2.1.3/.rumdl.toml

@@ -0,0 +1,72 @@
+# rumdl configuration file
+
+# Inherit settings from another config file (relative to this file's directory)
+# extends = "../base.rumdl.toml"
+
+# Global configuration options
+[global]
+
+flavor = "mkdocs"
+
+# List of rules to disable (uncomment and modify as needed)
+disable = ["MD013", "MD033", "MD041"]
+
+# List of rules to enable exclusively (replaces defaults; only these rules will run)
+# enable = ["MD001", "MD003", "MD004"]
+
+# Additional rules to enable on top of defaults (additive, does not replace)
+# Use this to activate opt-in rules like MD060, MD063, MD072, MD073, MD074
+# extend-enable = ["MD060", "MD063"]
+
+# Additional rules to disable on top of the disable list (additive)
+# extend-disable = ["MD041"]
+
+# List of file/directory patterns to include for linting (if provided, only these will be linted)
+# include = [
+#    "docs/*.md",
+#    "src/**/*.md",
+#    "README.md"
+# ]
+
+# List of file/directory patterns to exclude from linting
+exclude = [
+    # Common directories to exclude
+    ".git",
+    ".github",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+
+    # Specific files or patterns
+    "CHANGELOG.md",
+    "LICENSE.md",
+]
+
+# Respect .gitignore files when scanning directories (default: true)
+respect-gitignore = true
+
+# Markdown flavor/dialect (uncomment to enable)
+# Options: standard (default), gfm, commonmark, mkdocs, mdx, pandoc, quarto, obsidian, kramdown, azure_devops, myst, mdg
+# flavor = "mkdocs"
+
+# Rule-specific configurations (uncomment and modify as needed)
+
+# [MD003]
+# style = "atx"  # Heading style (atx, atx_closed, setext)
+
+# [MD004]
+# style = "asterisk"  # Unordered list style (asterisk, plus, dash, consistent)
+
+# [MD007]
+# indent = 4  # Unordered list indentation
+
+# [MD013]
+# line-length = 100  # Line length
+# code-blocks = false  # Exclude code blocks from line length check
+# tables = false  # Exclude tables from line length check
+# headings = true  # Include headings in line length check
+
+# [MD044]
+# names = ["rumdl", "Markdown", "GitHub"]  # Proper names that should be capitalized correctly
+# code-blocks = false  # Check code blocks for proper names (default: false, skips code blocks)

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mkdocstrings-matlab
-Version: 2.1.1
+Version: 2.1.3
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: MIT
@@ -26,6 +26,7 @@ Requires-Dist: griffe<3,>=2.0.0
 Requires-Dist: maxx<1,>=0.10.0
 Requires-Dist: mkdocs-autorefs<2,>=1.4
 Requires-Dist: mkdocstrings<2,>=1.0
+Requires-Dist: pymdown-extensions<12.2; python_version < '3.11'
 Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
 Description-Content-Type: text/markdown
 

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/api.md

@@ -11,4 +11,3 @@
       members:
         - handler
         - config
-

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/index.md

@@ -5,7 +5,7 @@ hide:
 
 --8<-- "README.md:header"
 
-## Preview 
+## Preview
 
 Let's us quickly see how auto-documentation works with mkdocstrings-matlab:
 
@@ -38,10 +38,10 @@ Given the function above, the rendered documentation here is created from the fo
 
 !!! note
 
-    Syntax highlighting of argument blocks will be incorrect with the default configuration due to the outdated MATLAB lexer in [Pygments](https://github.com/pygments/pygments/) and will be resolved after [our PR](https://github.com/pygments/pygments/pull/2887) is merged. 
+    Syntax highlighting of argument blocks will be incorrect with the default configuration due to the outdated MATLAB lexer in [Pygments](https://github.com/pygments/pygments/) and will be resolved after [our PR](https://github.com/pygments/pygments/pull/2887) is merged.
 
     In the meantime, the correct syntax highlighing can be configured by adding our branch as the dependency in `pyproject.toml`
-    
+
     ```toml title="pyproject.toml"
     dependencies = [
         "pygments @ git+https://github.com/watermarkhu/pygments.git@matlab",

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/license-page.md

@@ -7,6 +7,6 @@ hide:
 
 # License
 
-```
+```text
 --8<-- "LICENSE"
 ```

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/src/snippets/+module/module.md

@@ -23,7 +23,7 @@
         ```matlab
         --8<-- "docs/src/snippets/+module/do_something.m"
         ```
-    
+
     === ":material-file-code: `aClass.m`"
 
         ```matlab
@@ -40,4 +40,4 @@
 
         ```matlab
         --8<-- "docs/src/snippets/+module/+submodule/Contents.m"
-        ```
+        ```

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/src/snippets/+mymembers/mymembers.md

@@ -15,7 +15,7 @@
         ```matlab
         --8<-- "docs/src/snippets/+mymembers/Contents.m"
         ```
-    
+
     === ":material-file-code: `ThisClass.m`"
 
         ```matlab
@@ -32,4 +32,4 @@
 
         ```matlab
         --8<-- "docs/src/snippets/+mymembers/this_function.m"
-        ```
+        ```

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/src/snippets/+mynamespace/mynamespace.md

@@ -23,7 +23,7 @@
         ```matlab
         --8<-- "docs/src/snippets/+mynamespace/classA.m"
         ```
-    
+
     === ":material-file-code: `classB.m`"
 
         ```matlab

mkdocstrings_matlab-2.1.3/docs/src/snippets/+mynamespace/readme.md

@@ -0,0 +1 @@
+This is the docstring for mynamespace.

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/src/snippets/+undocumented/undocumented.md

@@ -14,7 +14,7 @@
         ```matlab
         --8<-- "docs/src/snippets/+undocumented/ClassWithoutDocstring.m"
         ```
-    
+
     === ":material-file-code: `function_with_docstring.m`"
 
         ```matlab

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/usage/configuration/docstrings.md

@@ -51,13 +51,13 @@ Possible values:
         ```matlab
         function message = greet(name)
             % Greet someone.
-            %  
+            %
             % Parameters:
             %     name: The name of the person to greet.
-            % 
+            %
             % Returns:
             %     message: A greeting message.
-            
+
             message = sprintf("Hello %s!", name)
         end
         ```
@@ -67,17 +67,17 @@ Possible values:
         ```matlab
         function message = greet(name)
             % Greet someone.
-            %  
+            %
             % Parameters
             % ----------
             % name
             %    The name of the person to greet.
-            % 
+            %
             % Returns
             % -------
             % message
             %    A greeting message.
-            
+
             message = sprintf("Hello %s!", name)
         end
         ```
@@ -87,10 +87,10 @@ Possible values:
         ```matlab
         function message = greet(name)
             % Greet someone.
-            %  
+            %
             % :param name: The name of the person to greet.
             % :return: A greeting message.
-            
+
             message = sprintf("Hello %s!", name)
         end
         ```
@@ -107,7 +107,7 @@ The options for the docstring parser.
 
 The Sphinx style does not offer any option.
 
-Most of the options in the linked pages will not have an effect to mkdocstrings-matlab, since here the objects are mocked as Python objects are docstrings are injected into the mocked objects. 
+Most of the options in the linked pages will not have an effect to mkdocstrings-matlab, since here the objects are mocked as Python objects are docstrings are injected into the mocked objects.
 
 === "mkdocs.yml"
 
@@ -176,7 +176,6 @@ Sections are parsed as structured data and can therefore be rendered in differen
 
 ???+ preview
 
-
     === "Table"
 
         Tables work well when you have lots of items with short names, type annotations, descriptions, etc.. With longer strings, the columns risk getting squished horizontally. In that case, the Spacy tables can help.
@@ -233,25 +232,24 @@ Sections are parsed as structured data and can therefore be rendered in differen
 
 Whether to load inputs and output parameters based on argument validation blocks.
 
-Similarly to Python, MATLAB is by default not a typed language. Function and method arguments are dynamically typed, in most cases. This provides flexibility, but is generally bad behavior if the code is meant for production or is intended to be exposed as an API. 
+Similarly to Python, MATLAB is by default not a typed language. Function and method arguments are dynamically typed, in most cases. This provides flexibility, but is generally bad behavior if the code is meant for production or is intended to be exposed as an API.
 
-In MATLAB R2019b the concept of [Argument Definitions](https://mathworks.com/help/matlab/input-and-output-arguments.html) was introduced. Within an [arguments](https://mathworks.com/help/matlab/ref/arguments.html) block, the type, size, or other aspects of the inputs (and outputs since R2022b) can be verified. 
+In MATLAB R2019b the concept of [Argument Definitions](https://mathworks.com/help/matlab/input-and-output-arguments.html) was introduced. Within an [arguments](https://mathworks.com/help/matlab/ref/arguments.html) block, the type, size, or other aspects of the inputs (and outputs since R2022b) can be verified.
 
 ```matlab
 function z = mySharedFunction(x,y,NameValueArgs)
    arguments
       x (1,1) double     % scalar
-      y double {mustBeVector,mustBePositive} 
+      y double {mustBeVector,mustBePositive}
       NameValueArgs.A string
       NameValueArgs.B string = "default"
-   end 
+   end
 ...
 end
 ```
 
 The mkdocstrings-matlab plugin is able to parse the argument blocks and extract the type and default information, and any comment after each Argument Definition will be parsed as the argument docstring. If if `parse_arguments` is enabled, sections will be rendered for the parameters, name-value pairs and the return arguments of functions and methods. These sections can be individually toggled with [`show_docstring_input_arguments`][], [`show_docstring_name_value_arguments`][] and [`show_docstring_output_arguments`][].
 
-
 === "mkdocs.yml"
 
     ```yaml
@@ -306,7 +304,7 @@ The mkdocstrings-matlab plugin is able to parse the argument blocks and extract
 
 !!! note
 
-    Prior to MATLAB R2019b, the functionality of the arguments blocks was most commonly achieved through [`inputParser`](https://mathworks.com/help/matlab/ref/inputparser.html). The validations created with `inputParser` will not be parsed by mkdocstrings-matlab, since it does not have a strict syntax as opposed to Argument Definitions. 
+    Prior to MATLAB R2019b, the functionality of the arguments blocks was most commonly achieved through [`inputParser`](https://mathworks.com/help/matlab/ref/inputparser.html). The validations created with `inputParser` will not be parsed by mkdocstrings-matlab, since it does not have a strict syntax as opposed to Argument Definitions.
 
 ### Name-value arguments from class properties
 
@@ -349,7 +347,7 @@ The name-value argument is parsed with the struct name (`opts`) as the argument
 
 Whether to merge the constructor method into the class' signature and docstring.
 
-By default, only the class name is rendered in headings. When merging, the constructor method parameters are added after the class name, like a signature, and the constructor method docstring is appended to the class' docstring. 
+By default, only the class name is rendered in headings. When merging, the constructor method parameters are added after the class name, like a signature, and the constructor method docstring is appended to the class' docstring.
 
 === "mkdocs.yml"
 
@@ -405,14 +403,12 @@ By default, only the class name is rendered in headings. When merging, the const
               merge_constructor_into_class: false
               parse_arguments: true
         ```
-        
+
         ::: Thing
             options:
               merge_constructor_into_class: false
               parse_arguments: true
 
-
-
 ## `show_if_no_docstring`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -471,7 +467,7 @@ With this option you can tell the Python handler to skip the docstring check.
             options:
               show_if_no_docstring: false
         ```
-        
+
         ::: +undocumented
             options:
               show_if_no_docstring: false
@@ -689,7 +685,6 @@ Whether to render the "Classes" sections of docstrings.
               show_docstring_classes: false
               members: false
 
-
 ## `show_docstring_namespaces`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -856,7 +851,7 @@ Whether to render the "Examples" sections of docstrings.
 ???+ preview
 
     === "With examples"
-        
+
         ```markdown
         ::: print_hello
             options:
@@ -884,7 +879,7 @@ Whether to render the "Examples" sections of docstrings.
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Parameters" sections of docstrings. The accepted title headings are `inputs` or `input arguments` (case-insensitive). 
+Whether to render the "Parameters" sections of docstrings. The accepted title headings are `inputs` or `input arguments` (case-insensitive).
 
 === "mkdocs.yml"
 
@@ -925,7 +920,7 @@ Whether to render the "Parameters" sections of docstrings. The accepted title he
             options:
               show_docstring_input_arguments: true
         ```
-        
+
         ::: do_something
             options:
               show_docstring_input_arguments: true
@@ -951,7 +946,7 @@ Whether to render the "Parameters" sections of docstrings. The accepted title he
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Name-value pairs" sections of docstrings. The accepted title headings are `name-value pairs` or `name-value arguments` (case-insensitive). 
+Whether to render the "Name-value pairs" sections of docstrings. The accepted title headings are `name-value pairs` or `name-value arguments` (case-insensitive).
 
 === "mkdocs.yml"
 
@@ -992,7 +987,7 @@ Whether to render the "Name-value pairs" sections of docstrings. The accepted ti
             options:
               show_docstring_name_value_arguments: true
         ```
-        
+
         ::: do_varargin
             options:
               show_docstring_name_value_arguments: true
@@ -1018,7 +1013,7 @@ Whether to render the "Name-value pairs" sections of docstrings. The accepted ti
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Returns" sections of docstrings. The accepted title headings are `outputs` or `output arguments` (case-insensitive). 
+Whether to render the "Returns" sections of docstrings. The accepted title headings are `outputs` or `output arguments` (case-insensitive).
 
 === "mkdocs.yml"
 
@@ -1059,7 +1054,7 @@ Whether to render the "Returns" sections of docstrings. The accepted title headi
             options:
               show_docstring_output_arguments: true
         ```
-        
+
         ::: do_output
             options:
               show_docstring_output_arguments: true

{mkdocstrings_matlab-2.1.1 → mkdocstrings_matlab-2.1.3}/docs/usage/configuration/general.md

@@ -43,7 +43,7 @@ Show the base classes of a class.
 
 ???+ preview
 
-    === "with bases" 
+    === "with bases"
 
         ```markdown
         ::: myClass
@@ -56,7 +56,7 @@ Show the base classes of a class.
                 show_bases: true
 
     === "without bases"
-        
+
         ```markdown
         ::: myClass
             options:
@@ -69,13 +69,12 @@ Show the base classes of a class.
 
 ## `show_inheritance_diagram`
 
-
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
 
 Show the inheritance diagram of a class using [Mermaid](https://mermaid.js.org/).
 
-With this option enabled, an inheritance diagram (as a flowchart) will be displayed after a class  signature. Each node will act as a cross-reference and will bring you to the relevant class' documentation when clicking on it.
+With this option enabled, an inheritance diagram (as a flowchart) will be displayed after a class signature. Each node will act as a cross-reference and will bring you to the relevant class' documentation when clicking on it.
 
 It should work out of the box with [Material for MkDocs](https://squidfunk.github.io), but it is recommended to follow the [setup guide](https://squidfunk.github.io/mkdocs-material/reference/diagrams/#other-diagram-types) for optimal support in Material for Mkdocs. For other themes, you must either setup [mkdocs-mermaid2](https://mkdocs-mermaid2.readthedocs.io/en/latest), or include Mermaid's Javascript code manually:
 
@@ -166,8 +165,8 @@ Show the source code of this object.
 
 ???+ preview
 
-    === "with source" 
-        
+    === "with source"
+
         ```markdown
         ::: myfunction
             options: