Members options¤
members¤
An explicit list of members to render.
Only members declared in this list will be rendered. A member without a docstring will still be rendered, even if show_if_no_docstring is set to false.
The members will be rendered in the specified order, regardless of the value of members_order. Note that members will still be grouped by category, according to the group_by_category option.
Passing a falsy value (no, false in YAML) or an empty list ([]) will tell the MATLAB handler not to render any member. Passing a truthy value (yes, true in YAML) will tell the MATLAB handler to render every member.
Any given value, except for an explicit None (null in YAML) will tell the handler to ignore filters for the object's members. Filters will still be applied to the next layers of members (grand-children).
plugins:
- mkdocstrings:
handlers:
matlab:
options:
members:
- hello # (1)
Most of the time it won't make sense to use this option at the global level.
::: +mymembers
options:
members:
- ThisClass
- this_function
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
Info
The default behavior (with unspecified members or members: null) is to use filters.
hidden_members¤
MATLAB's classes, methods and properties can be hidden by setting its attributes to Hidden or Hidden=true. By default, members that are specified as hidden will not be documented.
This takes precedence over members and filters, and also applies for inherited_members. This means that for any hidden member to be shown, hidden_members must be enabled, and further selection is possible via members and filters. Hidden members will be labeled Hidden, this can be disabled in show_labels.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
hidden_members: true
::: mymembers.ThisClass
options:
hidden_members: true
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
hidden_members: true
::: mymembers.ThisClass
options:
hidden_members: false
::: mymembers.ThisClass
options:
hidden_members: ['hidden_method']
private_members¤
MATLAB's methods and properties can be set to private via the Access attribute, and additionally via the SetAccess and GetAccess attributes for properties. The possible settings for these attributes are
- public
- protected
- private
- immutable (only for
SetAccess) - List of classes that have access to the current method or property.
To simplify the definition here, any property or method that do not have attribute Access set to public is considered a private member. If the GetAccess and/or SetAccess attribute is set in stead of Access for a property, it is consisered a private member if either the SetAccess attribute is not public or immutable or if the GetAccess attribute is not public.
flowchart TD
a[Access=public]
sg[SetAccess=public/immutable and GetAccess=public]
public[not private member]
private[private member]
a -- yes --> public
a -- no --> private
a -- "not specified" --> sg
sg -- no --> private
sg -- yes --> public
This takes precedence over members and filters, and also applies for inherited_members. This means that for any private member to be shown, private_members must be enabled, and further selection is possible via members and filters. Private members will be labeled with it access attribute setting, this can be disabled in show_labels.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
private_members: true
::: mymembers.ThisClass
options:
private_members: true
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
private_members: true
mymembers.ThisClass
¤
::: mymembers.ThisClass
options:
private_members: false
::: mymembers.ThisClass
options:
private_members: ['private_property']
inherited_members¤
An explicit list of inherited members (for classes) to render.
Inherited members are always fetched from classes that are in the same namespace as the currently rendered class. Otherwise, it must be ensured that the paths to the parent is included in paths. This is also the case for MATLAB built-in classes.
Passing a falsy value (no, false in YAML) or an empty list ([]) will tell the MATLAB handler not to render any inherited member. Passing a truthy value (yes, true in YAML) will tell the MATLAB handler to render every inherited member.
When all inherited members are selected with inherited_members: true, it is possible to specify both members and inherited members in the members list:
inherited_members: true
members:
- inherited_member_a
- inherited_member_b
- member_x
- member_y
The alternative is not supported:
inherited_members:
- inherited_member_a
- inherited_member_b
members:
- member_x
- member_y
...because it would make members ordering ambiguous/unspecified.
You can render inherited members only by setting inherited_members: true (or a list of inherited members) and setting members: false:
inherited_members: true
members: false
inherited_members:
- inherited_member_a
- inherited_member_b
members: false
You can render all declared members and all or specific inherited members by leaving members as null (default):
inherited_members:
- inherited_member_a
- inherited_member_b
# members: null # (1)
- In this case, only declared members will be subject to further filtering with
filtersanddocstrings.
inherited_members: true # (1)
# members: null
- In this case, both declared and inherited members will be subject to further filtering with
filtersanddocstrings.
You can render all declared members and all or specific inherited members, avoiding further filtering with filters and docstrings by setting members: true:
inherited_members: true
members: true
inherited_members:
- inherited_member_a
- inherited_member_b
members: true
The general rule is that declared or inherited members specified in lists are never filtered out.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
inherited_members: false
::: mymembers.ThisClass
options:
inherited_members: true
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
inherited_members: true
members_order¤
- Type
str"alphabetical"
The members ordering to use. Possible values:
alphabetical: order by the members names.source: order members as they appear in the source file.
The order applies for all members, recursively.
The order will be ignored for members that are explicitely sorted using the members option.
Note that members will still be grouped by category,
according to the group_by_category option.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
members_order: alphabetical
::: mymembers.ThisClass
options:
members_order: source
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
members_order: alphabetical
filters¤
A list of filters applied to filter objects based on their name.
Filters are regular expressions. These regular expressions are evaluated by Python and so must match the syntax supported by the re module. A filter starting with ! (negative filter) will exclude matching objects instead of including them.
The default value ([!^delete$|^disp$]) means: *render every object, except for members that are named delete or disp, which are two of MATLAB classes' built-in methods.
Each filter takes precedence over the previous one. This allows for fine-grain selection of objects by adding more specific filters. For example, you can start by unselecting objects that start with _, and add a second filter
that re-select objects that start with __. The default filters can therefore be rewritten like this:
filters:
- "!^_"
- "^__"
If there are no negative filters, the handler considers that everything is unselected first, and then selects things based on your positive filters. If there is at least one negative filter, the handler considers that everything is selected first, and then re-selects/unselects things based on your other filters. In short, filters: ["a"] means "keep nothing except names containing a", while filters: ["!a"] means "keep everything except names containing a".
An empty list of filters tells the MATLAB handler to render every object. The members option takes precedence over filters (filters will still be applied recursively to lower members in the hierarchy).
plugins:
- mkdocstrings:
handlers:
matlab:
options:
filters:
- "!^delete$|^disp$"
::: matlab_callable
options:
filters: []
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
filters: []
::: mymembers.ThisClass
options:
filters: ["method"]
group_by_category¤
- Type
boolTrue
Group the object members by categories: properties, classes, functions, and namespaces.
Members within a same category will be ordered according to the members_order option. You can use the show_category_heading option to also render a heading for each category.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
group_by_category: true
::: +mymembers
options:
group_by_category: false
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
show_subnamespaces¤
- Type
boolFalse
When rendering a namespace, show its subnamespaces recursively.
This is false by default, because most of the time we render only one namespace per page, and when rendering a full package (a tree of namespaces and their members) on a single page, we quickly run out of heading levels.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_subnamespaces: true
::: +matlab_namespace
options:
show_subnamespaces: false
Source files
📁 +module
├── 📁 +submodule
│ ├── 📄 Contents.m
│ └── 📄 subfunction.m
├── 📄 aClass.m
├── 📄 do_something.m
└── 📄 readme.m
Docstring of module.
Functions:
do_something: Do something.
Classes:
aClass: Summary
Namespaces:
submodule: This is a submodule
function do_something()
% Do something.
end
classdef aClass
% Summary.
%
% Long description.
%
% Methods:
% foo: Some method.
methods
function foo()
% Summary.
end
end
end
function subfunction
% This is a subfunction.
end
% This is a submodule
Preview
::: +module
options:
show_subnamespaces: true
summary¤
Whether to render summaries of namespaces, classes, functions (methods) and properties.
This option accepts a boolean (yes, true, no, false in YAML) or a dictionary with one or more of the following keys: namespaces, functions, classes, properties, with booleans as values. Class methods summary is (de)activated with the functions key. By default, summary is false, and by extension all values are false.
Examples:
summary: true
summary: false
summary:
properties: false
functions: true
namespaces: false
Summaries will be rendered as the corresponding docstring sections. For example, the summary for attributes will be rendered as an Attributes docstring section. The section will be rendered in accordance with the docstring_section_style option. If the objects appearing in the summary are also rendered on the page (or somewhere else on the site), their name will automatically link to their rendered documentation.
Hidden and private members will not be rendered in the summary, no matter the setting in hidden_members and private_members.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
summary: true
::: mymembers.ThisClass
options:
summary: false
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
summary: false
::: mymembers.ThisClass
options:
summary: true
mymembers.ThisClass
¤
Bases: mymembers.BaseClass
Class docstring.
Methods:
| Name | Description |
|---|---|
other_method |
Method docstring |
method |
Method docstring |
Attributes:
| Name | Type | Description |
|---|---|---|
public_property |
Public property docstring |
::: mymembers.ThisClass
options:
summary:
functions: true
Warning
In the summary, the title of the properties summary will be attributes, and the title of the namespaces summary will be modules. This is due to mkdocstrings-matlab's dependency on mkdocstrings-python. For now, mkdocstrings-matlab does not implement its own Jinja templates for rendering, leading to these summary titles.
show_labels¤
- Type
boolTrue
Whether to show labels of the members.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_labels: true
::: mymembers.ThisClass
options:
show_labels: false
Source files
📁 +mymembers
├── 📄 Contents.m
├── 📄 BaseClass.m
├── 📄 ThisClass.m
└── 📄 this_function.m
% This is the namespace docstring.
classdef ThisClass < mymembers.BaseClass
% Class docstring.
methods
function obj = other_method(obj, input)
% Method docstring
end
function obj = method(obj, input)
% Method docstring
end
function delete(obj)
% Destructor docstring
end
end
properties
public_property % Public property docstring
end
methods (Hidden)
function obj = hidden_method(obj, input)
% Hidden method docstring
end
end
methods (Access = private)
function obj = private_method(obj, input)
% Private method docstring
end
end
properties (Hidden)
hidden_property % Hidden property docstring
end
properties (SetAccess = private)
private_property % Private property docstring
end
end
classdef (Abstract) BaseClass
% Base class docstring.
methods
function obj = from_base(obj, input)
% Base method docstring
end
end
end
function this_function()
% Function docstring
end
Preview
::: mymembers.ThisClass
options:
private_members: true
show_labels: true
mymembers.ThisClass
¤
::: mymembers.ThisClass
options:
private_members: true
show_labels: false