Skip to main content

Sphinx "matlabdomain" extension

Project description

This package contains the MATLAB Sphinx domain and autodoc extensions.

Installation

Use Pip, Setuptools Easy Install or Python Distributions Utilities (Distutils).

Pip:

~$ pip install -U sphinxcontrib-matlabdomain

Easy Install:

~$ easy_install -U sphinxcontrib-matlabdomain

Distutils:

~/downloads$ curl https://pypi.python.org/packages/source/s/sphinxcontrib-matlabdomain/sphinxcontrib-matlabdomain-0.X.tar.gz
~/downloads$ tar -xf sphinxcontrib-matlabdomain-0.X.tar.gz
~/downloads$ cd sphinxcontrib_matlabdomain-0.X
~/downloads/sphinxcontrib_matlabdomain-0.X$ python setup.py install

Requirements

This package is an extension to Sphinx.

Usage

In general usage is the same as for documenting Python code.

Configuration

In your Sphinx conf.py file add sphinxcontrib.matlab to the list of extensions. To use auto-documentation features, also add sphinx.ext.autodoc to the list of extensions.

In order for the Sphinx MATLAB domain to auto-document MATLAB source code, set the config value of matlab_src_dir to the absolute path instead of adding them to sys.path. Currently only one MATLAB path can be specified, but all subfolders in that tree will be searched.

For convenience the primary domain can be set to mat.

Roles and Directives

Please see Sphinx Domains and sphinx.ext.autodoc for documentation on the use of roles and directives. MATLAB code can be documented using the following roles and directives:

Directive

MATLAB object

.. module:: foldername

folders, packages and namespaces

.. curremtmodule:: foldername

  • set folder but do not link

.. automodule:: foldername

  • auto-document

:mod:`foldername`

  • reference

.. function:: funcname

function definition and signature

.. autofunction:: funcname()

  • auto-document

:func:`funcname`

  • reference

.. class:: classname()

class definition and optional signature

.. autoclass:: classname

  • auto-document

:class:`classname`

  • reference

.. method:: methname()

method definition and signature

.. automethod:: methname

  • auto-document

:meth:`methname`

  • reference

.. staticmethod:: statmethname()

static method definition and signature

.. automethod:: statmethname

  • auto-document

:meth:`methname`

  • reference

.. attribute:: attrname

property definition

.. autoattribute:: attrname

  • auto-document

:attr:`attrname`

  • reference

Several options are available for auto-directives.

  • :members: auto-document public members

  • :show-inheritance: list bases

  • :undoc-members: document members without docstrings

  • :annotation: specifies attribute annotation instead of default

There are also several config values that can be set in conf.py that will affect auto-docementation.

  • autoclass_content can be set to class, both or init, which determines which docstring is used for classes. The constructor docstring is used when this is set to init.

  • autodoc_member_order can be set to alphabetical, groupwise or bysource.

  • autodoc_default_flags can be set to a list of options to apply. Use the no-flag directive option to disable this config value once.

Example: given the following MATLAB source in folder test_data:

classdef MyHandleClass < handle & my.super.Class
    % a handle class
    %
    % :param x: a variable

    %% some comments
    properties
        x % a property
    end
    methods
        function h = MyHandleClass(x)
            h.x = x
        end
        function x = get.x(obj)
        % how is this displayed?
            x = obj.x
        end
    end
    methods (Static)
        function w = my_static_function(z)
        % A static function in :class:`MyHandleClass`.
        %
        % :param z: input z
        % :returns: w

            w = z
        end
    end
end

Use the following to document:

Test Data
=========
This is the test data module.

.. automodule:: test_data

:mod:`test_data` is a really cool module.

My Handle Class
---------------
This is the handle class definition.

.. autoclass:: MyHandleClass
    :show-inheritance:
    :members:

Online Demo

The test docs in the repository are online here: http://bwanamarko.alwaysdata.net/matlabdomain/

Users

Changes

Project details


Release history Release notifications | RSS feed

This version

0.2.5

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-matlabdomain-0.2.5.zip (44.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page