You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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/).
13
+
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. The ASTinformation are imported as custom [Griffe](https://mkdocstrings.github.io/griffe/) objects and mocked for the [python handler](https://mkdocstrings.github.io/python/).
14
14
15
15
16
16
You can install this handler by specifying it as a dependency:
@@ -34,10 +34,10 @@ dependencies = [
34
34
35
35
-**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)
36
36
blocks to display input and output argument types and default values.
37
-
It is even able to automatically add cross-references o other objects from your API.
37
+
It is even able to automatically add cross-references to other objects from your API.
38
38
39
-
-**Recursive documentation of MATLAB [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html):**
40
-
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. Additionaly, the parent namespace documentation will be either extracted from the `Contents.m` or the `readme.md` file at the root of the namespace.
39
+
-**Recursive documentation of MATLAB [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html) and folders:**
40
+
just add `+` to the identifer for namespaces or the relative path for folder, and you get documentation for the entire directory. You don't need to inject documentation for each class, function, and script. Additionaly, the directory documentation will be either extracted from the `Contents.m` or the `readme.md` file at the root of the namespace or folder.
41
41
42
42
-**Support for documented properties:** properties definitions followed by a docstring will be recognized in classes.
Copy file name to clipboardExpand all lines: docs/usage/index.md
+45-2Lines changed: 45 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -56,6 +56,7 @@ If another handler was defined as default handler, you can explicitely ask for t
56
56
::: path.to.object
57
57
handler: matlab
58
58
```
59
+
### Namespaces
59
60
60
61
Entire [namespaces](https://mathworks.com/help/matlab/matlab_oop/namespaces.html) can be fully documented by prefixing the `+` character to the namespace that is to be documented. E.g. the following namespace
61
62
@@ -74,15 +75,57 @@ is documented with:
74
75
::: +mynamespace
75
76
```
76
77
77
-
The docstring of the namespace is taken from either the [`Contents.m`](https://mathworks.com/help/matlab/matlab_prog/create-a-help-summary-contents-m.html) or a `readme.md` that resides at the root level of the namespace, with `Contents.m` taking precedence over `readme.md`.
78
-
78
+
The docstring of the namespace is taken from either the [`Contents.m`](https://mathworks.com/help/matlab/matlab_prog/create-a-help-summary-contents-m.html) or a `readme.md` that resides at the root level of the namespace, with `Contents.m` taking precedence over `readme.md`.
79
79
80
80
Documenting a nested namespace requires only a single prefixed `+` at the start of the fully resolved path, e.g.
81
81
82
82
```md
83
83
::: +mynamespace.subnamespace
84
84
```
85
85
86
+
### Folders
87
+
88
+
Similarly to namepaces, all contents of a folder can be fully documented by specifying the relative path of a folder with respect to the `mkdocs.yml` config file. E.g. the following repository
89
+
90
+
```tree
91
+
src
92
+
module
93
+
myfunction.m
94
+
myClass.m
95
+
submodule
96
+
myfunction.m
97
+
+mynamespace
98
+
namespacefunction.m
99
+
docs
100
+
index.md
101
+
mkdocs.yml
102
+
```
103
+
104
+
is documented with:
105
+
106
+
```markdown
107
+
::: src/module
108
+
```
109
+
110
+
In the case above the function `module/submodule/myfunction.m` overshadows the function `module/myfunction.m` on the MATLAB path. This means that in the global namespace myfunction will always call `module/submodule/myfunction.m`, which is the function to be documented by `::: myfunction`.
111
+
112
+
While this kind of behavior is strictly recommended against, mkdocstrings-matlab does support documenting the shadowed function by using its path. The file extension is now stricty required.
113
+
114
+
```markdown
115
+
::: src/module/myfunction.m
116
+
```
117
+
118
+
!!! tip
119
+
120
+
A folder identifier must strictly contain the `/` character. For a folder `foo` that is in the same directory with `mkdocs.yml`, use `::: ./foo`.
121
+
122
+
!!! tip
123
+
124
+
If the `mkdocs.yml` lives inside of a subdirectly that does not contain source code, use relative paths e.g. `../src/module`.
125
+
126
+
!!! tip
127
+
128
+
Sub-selecting folder members are possible with the [members](./configuration/members.md) options.
0 commit comments