mkdocstrings-matlab 0.3.3__tar.gz → 0.4.1__tar.gz

mkdocstrings_matlab-0.4.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @watermarkhu

mkdocstrings_matlab-0.4.1/.github/workflows/docs.yaml

@@ -0,0 +1,69 @@
+name: Docs
+
+# Controls when the workflow will run
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: >-
+          Version of the documentation to publish
+        type: string
+        required: true
+      alias:
+        description: >-
+          (Versioned) Alias to use when publishing the versioned documentation with mike
+        type: string
+        default: "latest"
+      set-default:
+        description: >-
+          Set the alias as the default version
+        type: boolean
+        default: true
+      push:
+        description: >-
+          Push the documentation to the remote branch
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required to push to the documentation branch
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+  
+      - name: Sync dependencies
+        run: |
+          uv sync --no-dev --group docs
+
+      - name: Configure Git Credentials
+        run: |
+          git config --global user.name github-actions[bot]
+          git config --global user.email 41898282+github-actions[bot]@users.noreply.github.com
+  
+      - name: Build documentation with mike
+        env:
+          PUSH_DEPLOY: ${{ fromJson(inputs.push) && '--push' || '' }}
+        run: >
+          uv run mike deploy ${PUSH_DEPLOY} 
+          --branch gh-pages
+          --alias-type symlink
+          ${{ inputs.version }} ${{ inputs.alias }}
+      
+      - name: Set default alias for mike 
+        if: ${{ fromJson(inputs.set-default) }}
+        run: >
+          uv run mike set-default
+          --branch gh-pages 
+          --push
+          ${{ inputs.alias }}

mkdocstrings_matlab-0.4.1/.github/workflows/qualify.yaml

@@ -0,0 +1,88 @@
+name: Qualify
+
+on:
+  merge_group:
+  pull_request:
+    types:
+      - opened
+      - closed
+      - reopened
+      - synchronize
+      - labeled
+      - unlabeled
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  docs:
+    if: github.event.pull_request.draft == false
+    name: Test deploy documentation
+    uses: ./.github/workflows/docs.yaml
+    secrets: inherit
+    with:
+      version: __test__
+      alias: ""
+      set-default: false
+      push: false
+
+  check-semantic-version:
+    name: Check semantic version
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with: 
+        fetch-depth: 0
+        ref: ${{ github.sha }}
+
+    - name: Force correct release branch on workflow sha
+      run: |
+        git checkout -B ${{ github.ref_name }} ${{ github.sha }}
+
+    - name: Install the latest version of uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+
+    - name: Check next semantic version
+      run: |
+        uv sync --dev
+        OUTPUT=$(uv run semantic-release --noop version --print)
+        echo "$OUTPUT"
+        if [ -z "$OUTPUT" ]; then
+          echo "comment=No release will be made." >> $GITHUB_ENV
+        else
+          echo "comment=The next release will be v$OUTPUT" >> $GITHUB_ENV
+        fi
+
+    - name: Find Comment
+      id: fc
+      uses: peter-evans/find-comment@v3
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-author: 'github-actions[bot]'
+        body-includes: This comment was written by a bot!
+
+    - name: Create comment
+      if: steps.fc.outputs.comment-id == ''
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        body: |
+          ${{ env.comment }}
+          <!-- This comment was written by a bot! -->
+          
+    - name: Update comment
+      if: steps.fc.outputs.comment-id != ''
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        comment-id: ${{ steps.fc.outputs.comment-id }}
+        edit-mode: replace
+        body: |
+          ${{ env.comment }}
+          <!-- This comment was written by a bot! -->

mkdocstrings_matlab-0.4.1/.github/workflows/release.yaml

@@ -0,0 +1,105 @@
+name: Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    if: github.event.pull_request.merged == true
+    name: Semantic version release
+    runs-on: ubuntu-latest
+    environment: release
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+    concurrency: release
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+
+
+    - uses: actions/create-github-app-token@v1
+      id: app-token
+      with:
+        app-id: ${{ vars.APP_ID }}
+        private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+    - name: Get GitHub App User ID
+      id: get-user-id
+      env:
+        GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+
+    - run: |
+        git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+        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@v4
+      with:
+        fetch-depth: 0
+        ref: ${{ github.sha }}
+        token: ${{ steps.app-token.outputs.token }}
+        persist-credentials: true
+  
+    - name: Force correct release branch on workflow sha
+      run: |
+        git checkout -B ${{ github.ref_name }} ${{ github.sha }}
+
+    - name: Install the latest version of uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+
+    - name: Setup environment with UV
+      run: |
+        uv sync --dev
+        CURRENT_VERSION=$(uv run semantic-release --noop version --print-last-released)
+        NEXT_VERSION=$(uv run semantic-release --noop version --print)
+
+        if [ "$CURRENT_VERSION" = "$NEXT_VERSION" ]; then
+          echo "deploy=false" >> $GITHUB_ENV
+        else
+          echo "deploy=true" >> $GITHUB_ENV
+        fi
+
+    - name: Update version and changelogs
+      if: env.deploy
+      env:
+        GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+      run: >
+        uv run semantic-release -vv version 
+        --commit --tag --changelog --push
+        --skip-build --no-vcs-release
+
+    - name: Build and publish package distributions
+      if: env.deploy
+      run: |
+        uv build
+        uv publish
+
+    - name: Publish package distributions to GitHub Releases
+      if: env.deploy
+      env:
+        GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+      run: |
+        uv run semantic-release -vv publish
+
+  mkdocs:
+    name: Deploy documentation
+    needs: [publish]
+    uses: ./.github/workflows/docs.yaml
+    secrets: inherit
+    with:
+      version: ${{ needs.publish.outputs.tag }}
+      alias: latest
+      set-default: true
+      push: true

mkdocstrings_matlab-0.4.1/.python-version

@@ -0,0 +1 @@
+3.13

{mkdocstrings_matlab-0.3.3 → mkdocstrings_matlab-0.4.1}/.vscode/launch.json

@@ -14,13 +14,13 @@
             "jinja": true
         },
         {
-            "name": "Python Debugger: mkdocstrings test",
+            "name": "Python Debugger: mkdocstrings debug docs",
             "type": "debugpy",
             "request": "launch",
-            "program": "test/debug.py",
+            "program": "docs/debug.py",
             "console": "integratedTerminal",
             "justMyCode": false,
-            "jinja": true
+            "jinja": true,
         }
     ]
-}
+}

mkdocstrings_matlab-0.4.1/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "material-icon-theme.languages.associations": {
+        "jinja-html": "html"
+    },
+    "files.associations": {
+    "*.html": "jinja-html"
+   },
+    "emmet.includeLanguages": {
+        "jinja-html": "html"
+    },
+}

mkdocstrings_matlab-0.4.1/CHANGELOG.md

@@ -0,0 +1,84 @@
+# CHANGELOG
+
+
+## v0.4.1 (2025-01-03)
+
+### Bug Fixes
+
+- Default value of parameter_headings
+  ([#11](https://github.com/watermarkhu/mkdocstrings-matlab/pull/11),
+  [`651e25d`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/651e25db05fad867d51f360ab4b1c49ececce814))
+
+* fix default value of `parameter_headings` * add qualify workflow * documentation upgrades
+
+
+## v0.4.0 (2025-01-02)
+
+### Features
+
+- All options working ([#4](https://github.com/watermarkhu/mkdocstrings-matlab/pull/4),
+  [`83d1588`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/83d15882e0a00252b91d2d88a19bb2f903674ca4))
+
+* add general docs
+
+* add back parameter_headings option
+
+* improve headings section
+
+* bump mkdocstrings-python
+
+* done with headings section
+
+* fix inherited members, member order
+
+* better docs
+
+* fix docstring parameter handling
+
+* fixes
+
+* first attempt at hiding hidden and private members
+
+* working hidden and private members
+
+* finalize hidden and private members
+
+* first attempt summaries
+
+* summaries almost working
+
+* comments
+
+* updates
+
+* merge constructor
+
+* docs
+
+* hide previews
+
+* docstrings section done
+
+* finalize signatures
+
+* update logo
+
+* first attempt at workflows
+
+* finalize workflow
+
+- Fix workflows ([#6](https://github.com/watermarkhu/mkdocstrings-matlab/pull/6),
+  [`d90cf92`](https://github.com/watermarkhu/mkdocstrings-matlab/commit/d90cf925c992f83bb7102e22981968615310328e))
+
+* fix workflows
+
+* set dummy git credentials
+
+* set permission
+
+* forgotten input
+
+* fix
+
+
+## v0.3.3 (2024-12-19)

{mkdocstrings_matlab-0.3.3 → mkdocstrings_matlab-0.4.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Mark Shui Hu
+Copyright (c) 2025 Mark Shui Hu
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

{mkdocstrings_matlab-0.3.3 → mkdocstrings_matlab-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-matlab
-Version: 0.3.3
+Version: 0.4.1
 Summary: A MATLAB handler for mkdocstrings
 Author-email: Mark Hu <watermarkhu@gmail.com>
 License: ISC
@@ -22,9 +22,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: charset-normalizer>=3.3.2
-Requires-Dist: griffe>=1.5.1
-Requires-Dist: mkdocs==1.6.1
-Requires-Dist: mkdocstrings-python==1.10.9
+Requires-Dist: mkdocstrings-python==1.13.0
 Requires-Dist: mkdocstrings==0.27.0
 Requires-Dist: tree-sitter-matlab>=1.0.2
 Requires-Dist: tree-sitter>=0.23.2
@@ -34,10 +32,11 @@ Description-Content-Type: text/markdown
 
 <p align="center">A MATLAB handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
 
+[![qualify](https://github.com/watermarkhu/mkdocstrings-matlab/actions/workflows/qualify.yaml/badge.svg)](https://github.com/watermarkhu/mkdocstrings-matlab/actions/workflows/qualify.yaml)
+[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://watermarkhu.nl/mkdocstrings-matlab)
+[![pypi version](https://img.shields.io/pypi/v/mkdocstrings-matlab.svg)](https://pypi.org/project/mkdocstrings-matlab/)
 
----
-
-<p align="center"><img src="logo.png"></p>
+<p align="center"><img width=300px src="logo.svg"></p>
 
 The MATLAB handler uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) and its [MATLAB parser](https://github.com/acristoffers/tree-sitter-matlab) to collect documentation from MATLAB source code. Via the python bindings the Abstract Syntax Tree (AST) of the source code is traversed to extract useful information. The imported objected are imported as custom [Griffe](https://mkdocstrings.github.io/griffe/) objects and mocked for the [python handler](https://mkdocstrings.github.io/python/). 
 
@@ -50,7 +49,7 @@ You can install this handler by specifying it as a dependency:
 # adapt to your dependencies manager
 [project]
 dependencies = [
-    "mkdocstrings-matlab>=0.3",
+    "mkdocstrings-matlab>=0.4.0",
 ]
 ```
 

{mkdocstrings_matlab-0.3.3 → mkdocstrings_matlab-0.4.1}/README.md

@@ -2,10 +2,11 @@
 
 <p align="center">A MATLAB handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
 
+[![qualify](https://github.com/watermarkhu/mkdocstrings-matlab/actions/workflows/qualify.yaml/badge.svg)](https://github.com/watermarkhu/mkdocstrings-matlab/actions/workflows/qualify.yaml)
+[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://watermarkhu.nl/mkdocstrings-matlab)
+[![pypi version](https://img.shields.io/pypi/v/mkdocstrings-matlab.svg)](https://pypi.org/project/mkdocstrings-matlab/)
 
----
-
-<p align="center"><img src="logo.png"></p>
+<p align="center"><img width=300px src="logo.svg"></p>
 
 The MATLAB handler uses [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) and its [MATLAB parser](https://github.com/acristoffers/tree-sitter-matlab) to collect documentation from MATLAB source code. Via the python bindings the Abstract Syntax Tree (AST) of the source code is traversed to extract useful information. The imported objected are imported as custom [Griffe](https://mkdocstrings.github.io/griffe/) objects and mocked for the [python handler](https://mkdocstrings.github.io/python/). 
 
@@ -18,7 +19,7 @@ You can install this handler by specifying it as a dependency:
 # adapt to your dependencies manager
 [project]
 dependencies = [
-    "mkdocstrings-matlab>=0.3",
+    "mkdocstrings-matlab>=0.4.0",
 ]
 ```
 

mkdocstrings_matlab-0.4.1/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

mkdocstrings_matlab-0.4.1/docs/credits.md

@@ -0,0 +1,7 @@
+# Credits
+
+This project owes its existence to the incredible [`mkdocstrings`](https://mkdocstrings.github.io/), its primary extension [`mkdocstrings-python`](https://mkdocstrings.github.io/python/), and [`griffe`](https://github.com/mkdocstrings/griffe). These tools handle the templating of parsed content into HTML elements using Jinja templates, allowing much of the code and documentation to be reused and adapted for *mkdocstrings-matlab*. Special thanks to [@paramoy](https://fosstodon.org/@pawamoy) for his efforts.
+
+Moreover, `mkdocstrings` itself extends [`mkdocs`](https://www.mkdocs.org/) and [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/), which form the foundation of the entire mkdoc* suite of documentation tools.
+
+Finally, the parsing of MATLAB docstrings is powered by [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) and its [MATLAB parser](https://github.com/acristoffers/tree-sitter-matlab). These libraries enable the parsing of MATLAB source code with exceptional speed and accuracy.

{mkdocstrings_matlab-0.3.3/test → mkdocstrings_matlab-0.4.1/docs}/debug.py

@@ -15,17 +15,16 @@ def set_directory(path: Path):
         os.chdir(origin)
 
 
-config_path = Path(__file__).parent.resolve() / "mkdocs.yml"
+config_path = Path(__file__).parent.parent.resolve() / "mkdocs.yml"
 
 kwargs = {
     "dev_addr": None,
     "open_in_browser": False,
-    "livereload": True,
+    "livereload": False,
     "build_type": None,
     "watch_theme": True,
     "config_file": str(config_path),
     "strict": None,
-    "theme": None,
     "use_directory_urls": None,
 }
 

mkdocstrings_matlab-0.4.1/docs/logo.svg

@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   role="img"
+   viewBox="0 0 24 24"
+   version="1.1"
+   id="svg6"
+   sodipodi:docname="mkdocstrings-matlab.svg"
+   inkscape:version="1.1.2 (b8e25be833, 2022-02-05)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <defs
+     id="defs10" />
+  <sodipodi:namedview
+     id="namedview8"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     showgrid="false"
+     inkscape:zoom="36.375"
+     inkscape:cx="11.986254"
+     inkscape:cy="14.185567"
+     inkscape:window-width="3760"
+     inkscape:window-height="2126"
+     inkscape:window-x="-11"
+     inkscape:window-y="-11"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg6" />
+  <title
+     id="title2">Material for MkDocs</title>
+  <path
+     d="m 17.029,18.772 c -6.314,-9.47 0,0 -6.314,-9.47 L 18.582,4.062 24,1.354 V 16.84 l -5.417,2.709 z M 19.052,4.945 v 13.253 l 3.949,-1.975 V 2.97 Z"
+     id="path4"
+     style="display:inline;fill:#2777aa;fill-opacity:1"
+     sodipodi:nodetypes="cccccccccccc" />
+  <metadata
+     id="metadata71">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:title>Material for MkDocs</dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <path
+     d="M 17.806,19.938 12.389,22.647 0,16.451 V 4.063 L 5.417,1.354 c 12.389,18.584 0,0 12.389,18.584 z M 5.076,2.642 1.458,4.45 12.73,21.358 16.348,19.549 Z"
+     id="path148"
+     style="display:inline;fill:#ba5500;fill-opacity:1"
+     sodipodi:nodetypes="ccccccccccc" />
+</svg>

mkdocstrings_matlab-0.4.1/docs/snippets/+module/+submodule/Contents.m

@@ -0,0 +1 @@
+% This is a submodule

mkdocstrings_matlab-0.4.1/docs/snippets/+module/+submodule/subfunction.m

@@ -0,0 +1,3 @@
+function subfunction
+    % This is a subfunction.
+end

mkdocstrings_matlab-0.4.1/docs/snippets/+module/aClass.m

@@ -0,0 +1,15 @@
+classdef aClass
+    % Summary.
+    %
+    % Long description.
+    %
+    % Methods:
+    %     foo: Some method.
+
+    methods
+        function foo()
+            % Summary.
+        end
+    end
+end
+    

mkdocstrings_matlab-0.4.1/docs/snippets/+module/do_something.m

@@ -0,0 +1,3 @@
+function do_something()
+% Do something.
+end

mkdocstrings_matlab-0.4.1/docs/snippets/+module/module.md

@@ -0,0 +1,43 @@
+??? code "Source files"
+
+    === ":material-file-tree: tree"
+
+        ```tree
+        +module
+            +submodule
+                Contents.m
+                subfunction.m
+            aClass.m
+            do_something.m
+            readme.m
+        ```
+
+    === ":material-file-code: `readme.md`"
+
+        ```matlab
+        --8<-- "docs/snippets/+module/readme.md"
+        ```
+
+    === ":material-file-code: `do_something.m`"
+
+        ```matlab
+        --8<-- "docs/snippets/+module/do_something.m"
+        ```
+    
+    === ":material-file-code: `aClass.m`"
+
+        ```matlab
+        --8<-- "docs/snippets/+module/aClass.m"
+        ```
+
+    === ":material-file-code: `subfunction.m`"
+
+        ```matlab
+        --8<-- "docs/snippets/+module/+submodule/subfunction.m"
+        ```
+
+    === ":material-file-code: `Contents.m`"
+
+        ```matlab
+        --8<-- "docs/snippets/+module/+submodule/Contents.m"
+        ```

mkdocstrings_matlab-0.4.1/docs/snippets/+module/readme.md

@@ -0,0 +1,10 @@
+Docstring of module.
+
+Functions:
+    do_something: Do something.
+
+Classes:
+    aClass: Summary
+
+Namespaces:
+    submodule: This is a submodule

mkdocstrings_matlab-0.4.1/docs/snippets/+mymembers/BaseClass.m

@@ -0,0 +1,8 @@
+classdef (Abstract) BaseClass
+% Base class docstring.
+    methods
+        function obj = from_base(obj, input)
+            % Base method docstring
+        end
+    end
+end

mkdocstrings_matlab-0.4.1/docs/snippets/+mymembers/Contents.m

@@ -0,0 +1 @@
+% This is the namespace docstring.