mkdocstrings-matlab 0.2.3__tar.gz → 0.3.1__tar.gz

mkdocstrings_matlab-0.3.1/.python-version

@@ -0,0 +1 @@
+3.12

mkdocstrings_matlab-0.3.1/.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "jinja": true
+        },
+        {
+            "name": "Python Debugger: mkdocstrings test",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "test/debug.py",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "jinja": true
+        }
+    ]
+}

mkdocstrings_matlab-0.3.1/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.analysis.typeCheckingMode": "standard"
+}

mkdocstrings_matlab-0.3.1/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2024 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
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

mkdocstrings_matlab-0.3.1/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: mkdocstrings-matlab
+Version: 0.3.1
+Summary: A MATLAB handler for mkdocstrings
+Author-email: Mark Hu <watermarkhu@gmail.com>
+License: ISC
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
+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.0
+Requires-Dist: mkdocstrings[python]>=0.18
+Requires-Dist: tree-sitter-matlab>=1.0.2
+Requires-Dist: tree-sitter>=0.23.2
+Description-Content-Type: text/markdown
+
+<h1 align="center">mkdocstrings-matlab</h1>
+
+<p align="center">A MATLAB handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
+
+
+---
+
+<p align="center"><img src="logo.png"></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/). 
+
+## Installation
+
+You can install this handler by specifying it as a dependency:
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+    "mkdocstrings-matlab>=0.3",
+]
+```
+
+## Features
+
+- **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to
+  [Tree-sitter](https://tree-sitter.github.io/tree-sitter/).
+
+- **Support for argument validation blocks:** Tree-sitter collects your [function and method argument validation](https://mathworks.com/help/matlab/matlab_prog/function-argument-validation-1.html)
+   blocks to display input and output argument types and default values. 
+   It is even able to automatically add cross-references o other objects from your API.
+
+- **Recursive documentation of MATLAB [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html):** 
+  just add `+` to the identifer, and you get the full namespace docs. You don't need to inject documentation for each class, function, and script.
+
+- **Support for documented properties:** properties definitions followed by a docstring will be recognized in classes. 
+
+- **Multiple docstring-styles support:** common support for Google-style, Numpydoc-style,
+  and Sphinx-style docstrings. See [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/) on docstrings support.
+
+- **Admonition support in Google docstrings:** blocks like `Note:` or `Warning:` will be transformed
+  to their [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) equivalent.
+  *We do not support nested admonitions in docstrings!*
+
+- **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table
+  of Contents, which is nicely displayed by the Material theme. Thanks to *mkdocstrings* cross-reference ability,
+  you can reference other objects within your docstrings, with the classic Markdown syntax:
+  `[this object][namespace.subnamespace.object]` or directly with `[namespace.subnamespace.object][]`
+
+- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the MATLAB object.

mkdocstrings_matlab-0.3.1/README.md

@@ -0,0 +1,51 @@
+<h1 align="center">mkdocstrings-matlab</h1>
+
+<p align="center">A MATLAB handler for <a href="https://github.com/mkdocstrings/mkdocstrings"><i>mkdocstrings</i></a>.</p>
+
+
+---
+
+<p align="center"><img src="logo.png"></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/). 
+
+## Installation
+
+You can install this handler by specifying it as a dependency:
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+    "mkdocstrings-matlab>=0.3",
+]
+```
+
+## Features
+
+- **Data collection from source code**: collection of the object-tree and the docstrings is done thanks to
+  [Tree-sitter](https://tree-sitter.github.io/tree-sitter/).
+
+- **Support for argument validation blocks:** Tree-sitter collects your [function and method argument validation](https://mathworks.com/help/matlab/matlab_prog/function-argument-validation-1.html)
+   blocks to display input and output argument types and default values. 
+   It is even able to automatically add cross-references o other objects from your API.
+
+- **Recursive documentation of MATLAB [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html):** 
+  just add `+` to the identifer, and you get the full namespace docs. You don't need to inject documentation for each class, function, and script.
+
+- **Support for documented properties:** properties definitions followed by a docstring will be recognized in classes. 
+
+- **Multiple docstring-styles support:** common support for Google-style, Numpydoc-style,
+  and Sphinx-style docstrings. See [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/) on docstrings support.
+
+- **Admonition support in Google docstrings:** blocks like `Note:` or `Warning:` will be transformed
+  to their [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) equivalent.
+  *We do not support nested admonitions in docstrings!*
+
+- **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table
+  of Contents, which is nicely displayed by the Material theme. Thanks to *mkdocstrings* cross-reference ability,
+  you can reference other objects within your docstrings, with the classic Markdown syntax:
+  `[this object][namespace.subnamespace.object]` or directly with `[namespace.subnamespace.object][]`
+
+- **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code of the MATLAB object.

mkdocstrings_matlab-0.3.1/docs/index.md

@@ -0,0 +1,6 @@
+---
+hide:
+- feedback
+---
+
+--8<-- "README.md"

mkdocstrings_matlab-0.3.1/docs/license.md

@@ -0,0 +1,10 @@
+---
+hide:
+- feedback
+---
+
+# License
+
+```
+--8<-- "LICENSE"
+```

mkdocstrings_matlab-0.3.1/docs/stylesheets/extra.css

@@ -0,0 +1,3 @@
+[data-md-color-scheme="matlab"] {
+--md-primary-fg-color:        #2777aa;
+}

mkdocstrings_matlab-0.3.1/docs/usage/docstrings/google.md

@@ -0,0 +1,28 @@
+# Google style
+
+## :warning: Work in Progress!
+
+### Google-style admonitions
+
+With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent.
+For example:
+
+=== "Docstring"
+    ```python
+    """
+    Note:
+        It looks like a section, but it will be rendered as an admonition.
+
+    Tip: You can even choose a title.
+        This admonition has a custom title!
+    """
+    ```
+    
+=== "Result"
+    NOTE: It looks like a section, but it will be rendered as an admonition.
+
+    TIP: **You can even choose a title.**  
+    This admonition has a custom title!
+
+See [Napoleon's documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
+See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).

mkdocstrings_matlab-0.3.1/docs/usage/docstrings/numpy.md

@@ -0,0 +1,11 @@
+# Numpydoc style
+
+## :warning: Work in Progress!
+
+NOTE: As Numpy-style is partially supported by the underlying parser,
+you may experience problems in the building process if your docstring
+has a `Methods` section in the class docstring
+(see [#366](https://github.com/mkdocstrings/mkdocstrings/issues/366)).
+
+See [Numpydoc's documentation](https://numpydoc.readthedocs.io/en/latest/format.html).
+See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).

mkdocstrings_matlab-0.3.1/docs/usage/docstrings/sphinx.md

@@ -0,0 +1,6 @@
+# Sphinx style
+
+## :warning: Work in Progress!
+
+See [Sphinx's documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).
+See the supported docstring sections on [Griffe's documentation](https://mkdocstrings.github.io/griffe/docstrings/).

mkdocstrings_matlab-0.3.1/docs/usage/index.md

@@ -0,0 +1,140 @@
+# Usage
+
+## Installation
+
+You can install this handler by specifying it as a dependency:
+
+```toml title="pyproject.toml"
+# PEP 621 dependencies declaration
+# adapt to your dependencies manager
+[project]
+dependencies = [
+    "mkdocstrings-matlab>=0.3",
+]
+```
+
+For *mkdocstrings* the default will be the Python handler. You can change the default handler,
+or explicitely set the MATLAB handler as default by defining the `default_handler`
+configuration option of `mkdocstrings` in `mkdocs.yml`:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+    default_handler: matlab
+```
+
+## Injecting documentation
+
+With the MATLAB handler installed and configured as default handler,
+you can inject documentation for a module, class, function, or any other MATLAB object
+with *mkdocstrings*' [autodoc syntax], in your Markdown pages:
+
+```md
+::: path.to.object
+```
+
+If another handler was defined as default handler, 
+you can explicitely ask for the MATLAB handler to be used when injecting documentation
+with the `handler` option:
+
+```md
+::: path.to.object
+    handler: matlab
+```
+
+## Configuration
+
+When installed, the MATLAB handler becomes the default *mkdocstrings* handler.
+You can configure it in `mkdocs.yml`:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        ...  # the Python handler configuration
+```
+
+### Global-only options
+
+Some options are **global only**, and go directly under the handler's name.
+
+
+
+#### `paths`
+
+This option is used to set the [MATLAB search path](https://mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). 
+The MATLAB search path is a subset of all the folders in the file system.
+The order of folders on the search path is important. 
+When files with the same name appear in multiple folders on the search path, 
+MATLAB uses the one found in the folder nearest to the top of the search path.
+
+Non-absolute paths are computed as relative to MkDocs configuration file. Example:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+    handlers:
+      matlab:
+        paths: [src]  # search files in the src folder
+```
+
+
+#### `load_external_modules`
+
+This option allows you to specify whether the handler should recursively search through the directories specified in the `paths` option. When set to `true`, the handler will look for MATLAB files in all subdirectories of the specified paths.
+
+Example:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+    handlers:
+      matlab:
+        paths: [src]  # search files in the src folder
+        paths_recursive: true  # search recursively in subfolders
+```
+
+
+
+### Global/local options
+
+The other options can be used both globally *and* locally, under the `options` key.
+For example, globally:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          do_something: true
+```
+
+...and locally, overriding the global configuration:
+
+```md title="docs/some_page.md"
+::: package.module.class
+    options:
+      do_something: false
+```
+
+These options affect how the documentation is collected from sources and rendered.
+See the following tables summarizing the options, and get more details for each option
+in the following pages:
+
+- [General options](configuration/general.md): various options that do not fit in the other categories
+- [Headings options](configuration/headings.md): options related to headings and the table of contents
+    (or sidebar, depending on the theme used)
+- [Members options](configuration/members.md): options related to filtering or ordering members
+    in the generated documentation
+- [Docstrings options](configuration/docstrings.md): options related to docstrings (parsing and rendering)
+- [Signature options](configuration/signatures.md): options related to signatures and type annotations
+
+#### Options summary
+
+::: mkdocstrings_handlers.matlab.handler.MatlabHandler.default_config
+    handler: python
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false

mkdocstrings_matlab-0.3.1/mkdocs.yml

@@ -0,0 +1,226 @@
+site_name: "mkdocstrings-matlab"
+site_description: "A MATLAB handler for mkdocstrings."
+# site_url: "https://mkdocstrings.github.io/python"
+repo_url: "https://github.com/watermarkhu/mkdocstrings-matlab"
+repo_name: "watermarkhu/mkdocstrings-matlabn"
+site_dir: "site"
+watch: [mkdocs.yml, README.md, src/mkdocstrings_handlers]
+copyright: Copyright © 2024 Mark Shui Hu
+edit_uri: edit/main/docs/
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+nav:
+- Home:
+  - Overview: index.md
+#   - Changelog: changelog.md
+#   - Credits: credits.md
+  - License: license.md
+- Usage:
+  - usage/index.md
+#   - Configuration options:
+#     - General: usage/configuration/general.md
+#     - Headings: usage/configuration/headings.md
+#     - Members: usage/configuration/members.md
+#     - Docstrings: usage/configuration/docstrings.md
+#     - Signatures: usage/configuration/signatures.md
+  - Docstring styles:
+    - Google: usage/docstrings/google.md
+    - Numpy: usage/docstrings/numpy.md
+    - Sphinx: usage/docstrings/sphinx.md
+# # defer to gen-files + literate-nav
+# - API reference:
+#   - mkdocstrings-python: reference/
+# - Development:
+#   - Contributing: contributing.md
+#   - Code of Conduct: code_of_conduct.md
+#   # - Coverage report: coverage.md
+# - Insiders:
+#   - insiders/index.md
+#   - Getting started:
+#     - Installation: insiders/installation.md
+#     - Changelog: insiders/changelog.md
+# - mkdocstrings: https://mkdocstrings.github.io/
+
+theme:
+  name: material
+  logo: logo.png
+  features:
+  - announce.dismiss
+  - content.action.edit
+  - content.action.view
+  - content.code.annotate
+  - content.code.copy
+  - content.tooltips
+  - navigation.footer
+  - navigation.indexes
+  - navigation.sections
+  - navigation.tabs
+  - navigation.tabs.sticky
+  - navigation.top
+  - search.highlight
+  - search.suggest
+  - toc.follow
+  palette:
+  - media: "(prefers-color-scheme)"
+    toggle:
+      icon: material/brightness-auto
+      name: Switch to light mode
+  - media: "(prefers-color-scheme: light)"
+    scheme: matlab
+    toggle:
+      icon: material/weather-sunny
+      name: Switch to dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    primary: black
+    accent: lime
+    toggle:
+      icon: material/weather-night
+      name: Switch to system preference
+
+extra_css:
+  - stylesheets/extra.css
+
+markdown_extensions:
+- abbr
+- attr_list
+- admonition
+
+- footnotes
+- md_in_html
+- pymdownx.blocks.admonition
+- pymdownx.blocks.details
+- pymdownx.blocks.tab:
+    alternate_style: true
+    slugify: !!python/object/apply:pymdownx.slugs.slugify
+      kwds:
+        case: lower
+- pymdownx.emoji:
+    emoji_index: !!python/name:material.extensions.emoji.twemoji
+    emoji_generator: !!python/name:material.extensions.emoji.to_svg
+- pymdownx.highlight:
+    pygments_lang_class: true
+- pymdownx.magiclink
+- pymdownx.snippets:
+    # auto_append: [docs/.glossary.md]
+    base_path: [!relative $config_dir]
+    check_paths: true
+- pymdownx.superfences:
+    custom_fences:
+    - name: mermaid
+      class: mermaid
+      format: !!python/name:pymdownx.superfences.fence_code_format
+- pymdownx.tabbed:
+    alternate_style: true
+    slugify: !!python/object/apply:pymdownx.slugs.slugify
+      kwds:
+        case: lower
+- pymdownx.tasklist:
+    custom_checkbox: true
+- toc:
+    permalink: "¤"
+
+plugins:
+- autorefs
+- search
+- markdown-exec
+- callouts
+# - gen-files:
+#     scripts:
+#     - scripts/gen_ref_nav.py
+# - literate-nav:
+#     nav_file: SUMMARY.md
+- mkdocs-material-matlab
+- mkdocstrings:
+    default_handler: matlab
+    handlers:
+      matlab:
+        paths: ["docs/snippets"]
+        options:
+          show_inheritance_diagram: true
+          show_source: true
+          heading_level: 2
+          show_root_heading: true
+          show_root_toc_entry: false
+          show_root_full_path: true
+          show_root_members_full_path: false
+          show_object_full_path: false
+          show_category_heading: false
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
+
+          inherited_members: false
+          member_order: "bysource"
+          summary: true
+          show_labels: true
+
+          docstring_style: google
+          docstring_section_style: table
+          create_from_argument_blocks: true
+          merge_constructor_into_class: true
+          show_if_no_docstring: true
+          show_docstring_attributes": true
+          show_docstring_functions": true
+          show_docstring_classes": true
+          show_docstring_modules": true 
+          show_docstring_description": true
+          show_docstring_examples": true
+          show_docstring_other_parameters": true
+          show_docstring_parameters": false
+          show_docstring_raises": true
+          show_docstring_receives": true
+          show_docstring_returns": false
+          show_docstring_warns": true
+
+          annotations_path: full
+          show_signature: true
+          show_signature_annotations: false
+          separate_signature: false 
+      python:
+        paths: [src, docs/snippets]
+        import:
+        - https://docs.python.org/3/objects.inv
+        - https://mkdocstrings.github.io/objects.inv
+        - https://mkdocstrings.github.io/autorefs/objects.inv
+        - https://mkdocstrings.github.io/griffe/objects.inv
+        - https://python-markdown.github.io/objects.inv
+        options:
+          docstring_options:
+            ignore_init_summary: true
+          docstring_section_style: list
+          filters: ["!^_"]
+          heading_level: 1
+          inherited_members: true
+          merge_init_into_class: true
+          parameter_headings: true
+          preload_modules: [mkdocstrings]
+          relative_crossrefs: true
+          scoped_crossrefs: true
+          separate_signature: true
+          show_bases: false
+          show_inheritance_diagram: true
+          show_root_heading: true
+          show_root_full_path: false
+          show_signature_annotations: true
+          show_source: false
+          show_symbol_type_heading: true
+          show_symbol_type_toc: true
+          signature_crossrefs: true
+          summary: true
+          unwrap_annotated: true
+
+- git-revision-date-localized:
+    enabled: !ENV [DEPLOY, false]
+    enable_creation_date: true
+    type: timeago
+- minify:
+    minify_html: !ENV [DEPLOY, false]
+- group:
+    enabled: !ENV [MATERIAL_INSIDERS, false]
+    plugins:
+    - typeset
+