Autodoc Directives

Autodoc directives automatically generate documentation from your MATLAB source code. This page covers all available directives and their options.

Overview

The MATLAB domain provides these autodoc directives:

  • automodule - Document entire modules/packages

  • autofunction - Document functions

  • autoclass - Document classes

  • automethod - Document class methods

  • autoattribute - Document class properties/attributes

  • autoexception - Document exception classes (if applicable)

All directives extract docstrings and signatures from your .m files automatically.

autofunction

Documents a MATLAB function.

Basic Usage

.. autofunction:: myfunction

This extracts the function signature and docstring from myfunction.m.

With Package Prefix

.. autofunction:: mypackage.utilities.helper

Options

:noindex:

Don’t add this function to the index.

.. autofunction:: myfunction
   :noindex:

Example

Given this MATLAB function:

function result = calculate_area(width, height)
% CALCULATE_AREA Calculate rectangle area
%
% Args:
%     width (double): Width of rectangle
%     height (double): Height of rectangle
%
% Returns:
%     double: Area of the rectangle

result = width * height;
end

This directive:

.. autofunction:: calculate_area

Produces documentation showing:

  • Function name and signature

  • Full docstring

  • Parameter descriptions

  • Return value description

autoclass

Documents a MATLAB class.

Basic Usage

.. autoclass:: MyClass

Options

:members:

Include all members (methods and properties).

.. autoclass:: MyClass
   :members:
:undoc-members:

Include members without docstrings.

.. autoclass:: MyClass
   :members:
   :undoc-members:
:show-inheritance:

Show the class inheritance diagram.

.. autoclass:: MyClass
   :show-inheritance:
:member-order:

Control the order of members. Options: alphabetical, bysource, groupwise.

.. autoclass:: MyClass
   :members:
   :member-order: bysource
:exclude-members:

Exclude specific members.

.. autoclass:: MyClass
   :members:
   :exclude-members: internal_method, helper
:special-members:

Include special methods (like constructors).

.. autoclass:: MyClass
   :members:
   :special-members: __init__
:private-members:

Include private members (methods starting with underscore or in private blocks).

.. autoclass:: MyClass
   :members:
   :private-members:

Selective Members

Include only specific members:

.. autoclass:: MyClass
   :members: method1, method2, property1

Example

Given this MATLAB class:

classdef Calculator
    % CALCULATOR A simple calculator class
    %
    % This class provides basic arithmetic operations.

    properties
        % LASTRESULT The result of the last operation
        LastResult
    end

    methods
        function obj = Calculator()
            % CALCULATOR Constructor
            obj.LastResult = 0;
        end

        function result = add(obj, a, b)
            % ADD Add two numbers
            %
            % Args:
            %     a (double): First number
            %     b (double): Second number
            %
            % Returns:
            %     double: Sum of a and b

            result = a + b;
            obj.LastResult = result;
        end
    end
end

This directive:

.. autoclass:: Calculator
   :members:
   :undoc-members:

Documents the entire class with all methods and properties.

automodule

Documents an entire MATLAB package or directory.

Basic Usage

.. automodule:: mypackage

For MATLAB packages (directories starting with +):

.. automodule:: +mypackage

Options

:members:

Include all functions and classes in the module.

.. automodule:: mypackage
   :members:
:undoc-members:

Include members without docstrings.

.. automodule:: mypackage
   :members:
   :undoc-members:
:show-inheritance:

Show inheritance diagrams for all classes.

.. automodule:: mypackage
   :members:
   :show-inheritance:
:synopsis:

Provide a synopsis that appears in module listings.

.. automodule:: mypackage
   :synopsis: Utility functions for data processing
:platform:

Specify platforms (e.g., “Windows, Linux”).

.. automodule:: mypackage
   :platform: MATLAB R2020b and later

Example

For this MATLAB package structure:

+mypackage/
├── helper.m
├── validator.m
└── +subpackage/
    └── tool.m

This directive:

.. automodule:: mypackage
   :members:

Documents all functions in the package.

automethod

Documents a specific class method.

Basic Usage

.. automethod:: MyClass.mymethod

This is useful when you want to document a specific method without including the entire class.

Options

Same as autofunction:

  • :noindex:

Example

.. autoclass:: Calculator
   :noindex:

.. automethod:: Calculator.add

.. automethod:: Calculator.multiply

autoattribute

Documents a class property or attribute.

Basic Usage

.. autoattribute:: MyClass.property_name

Options

:annotation:

Add a custom annotation.

.. autoattribute:: MyClass.MAX_SIZE
   :annotation: = 100

Example

Given a class with properties:

classdef DataProcessor
    properties
        % BUFFER_SIZE Maximum buffer size
        BufferSize = 1024
    end
end

Document the property:

.. autoattribute:: DataProcessor.BufferSize

Combining Directives

Full Class Documentation

Document a class completely with methods and properties:

API Reference
=============

Calculator Class
----------------

.. autoclass:: Calculator
   :members:
   :undoc-members:
   :show-inheritance:

Selective Documentation

Document only specific parts:

Important Functions
===================

.. autofunction:: validate_input

.. autofunction:: process_data

Calculator Class
================

.. autoclass:: Calculator
   :members: add, subtract
   :noindex:

Package Overview

Document multiple packages:

Utility Packages
================

Core Utilities
--------------
.. automodule:: utils.core
   :members:

Data Utilities
--------------
.. automodule:: utils.data
   :members:

Directive Options Reference

Common Options

These options work with most directives:

Option

Description

:noindex:

Don’t add to index

:members:

Include all members (classes/modules)

:undoc-members:

Include undocumented members

:show-inheritance:

Show inheritance diagrams (classes)

:member-order:

Order: alphabetical, bysource, groupwise

:exclude-members:

Comma-separated list to exclude

:private-members:

Include private members

:special-members:

Include special members

Tips and Best Practices

  1. Start with :members:

    .. autoclass:: MyClass
   :members:

    Then add :undoc-members: if needed.

  2. Use :show-inheritance: for class hierarchies

    Helps users understand relationships between classes.

  3. Exclude internal methods

    .. autoclass:: MyClass
   :members:
   :exclude-members: internal_helper, temp_method

  4. Order members logically

    Use :member-order: bysource to preserve your source file order.

  5. Document packages with automodule

    More convenient than listing every function.

Troubleshooting

Function/Class Not Found

  • Verify the name matches the file name exactly (case-sensitive)

  • Check that matlab_src_dir is configured correctly

  • Ensure the file is in matlab_src_dir or a subdirectory

No Documentation Appearing

  • Check that your MATLAB files have docstring comments

  • Verify docstrings are in the correct format (starting with %)

  • Run make clean && make html to rebuild

Members Not Showing

  • Add :members: option to autoclass or automodule

  • Add :undoc-members: if methods lack docstrings

  • Check :exclude-members: isn’t filtering them out

See Also