GithubHelp home page GithubHelp logo

dbhart / matlabdomain Goto Github PK

View Code? Open in Web Editor NEW

This project forked from sphinx-contrib/matlabdomain

0.0 0.0 0.0 872 KB

A Sphinx extension for documenting Matlab code

License: Other

Python 84.13% MATLAB 11.18% M 0.04% Makefile 2.06% Batchfile 2.58%

matlabdomain's Introduction

Github Actions github-action-badge

sphinxcontrib-matlabdomain -- Sphinx domain for auto-documenting MATLAB

This extension provides a Sphinx domain for automatically generating doumentation from MATLAB source files. It is modelled after the Python autodoc.

The extension allows you to have your documentation and source files together and use the powerful Sphinx documentation tool. All your MATLAB file help text can be automatically included in the your documentation and output as for instance HTML.

The extension works really well with sphinx.ext.napoleon.

Recent Changes.

Usage

The Python package must be installed with:

pip install -U sphinxcontrib-matlabdomain

In general, the usage is the same as for documenting Python code. The package is tested with Python >= 3.8 and Sphinx >=4.0.0.

For a Python 2 compatible version the package must be installed with:

pip install sphinxcontrib-matlabdomain==0.11.8

Configuration

In your Sphinx conf.py file add sphinxcontrib.matlab to the list of extensions.

extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc']

For convenience the primary domain can be set to mat with.:

primary_domain = "mat"

Additional Configuration

matlab_src_dir
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. Currently only one MATLAB path can be specified, but all subfolders in that tree will be searched.
matlab_src_encoding
The encoding of the MATLAB files. By default, the files will be read as utf-8 and parsing errors will be replaced using ? chars. Added in Version 0.9.0.
matlab_keep_package_prefix
Determines if the MATLAB package prefix + is displayed in the generated documentation. Default is False. When False, packages are still referred to in ReST using +pakage.+subpkg.func but the output will be pakage.other.func(). Added in Version 0.11.0.
matlab_show_property_default_value
Show property default values in the rendered document. Default is False, which is what MathWorks does in their documentation. Added in Version 0.16.0.
matlab_short_links

Shorten all class, package and functions to the minimum length. This assumes that everything is in the path as we would expect it in MATLAB. This will resemble a more MATLAB-like presentation. If it is True is forces matlab_keep_package_prefix = False. Further, it allows for much shorter and cleaner references. Example, given a path to a class like target.subfolder.ClassFoo. * With False:

:class:`target.subfolder.ClassFoo`
  • With True:

    :class:`ClassFoo`
    

Default is False. Added in Version 0.19.0.

If you want the closest to MATLAB documentation style, use matlab_short_links = True in your conf.py file.

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
.. currentmodule:: 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
.. script:: scriptname script definition
.. autoscript:: scriptname
  • auto-document
:scpt:`scriptname`
  • 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
.. application:: appname application definition
.. autoapplication:: appname
  • auto-document
:app:`appname`
  • 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.

Note

The module roles and directives create a psuedo namespace for MATLAB objects, similar to a package. They represent the path to the folder containing the MATLAB object. If no module is specified then Sphinx will assume that the object is a built-in.

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

        % Multiple lines before a
        % property can also be used
        y
    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:

In version 0.19.0 the .. automodule:: directive can also take a . as argument, which allows you to document classes or functions in the root of matlab_src_dir.

Module Index

Since version 0.10.0 the MATLAB Module Index should be linked to with:

`MATLAB Module Index <mat-modindex.html>`_

Older versions, used the Python Module Index, which was linked to with:

:ref:`modindex`

Documenting Python and MATLAB sources together

Since version 0.10.0 MATLAB and Python sources can be (auto-)documented in the same Sphinx documentation. For this to work, do not set the primary domain.

Instead use the mat: prefix before the desired directives:

.. automodule:: func
.. autofunction:: func.main

.. mat:automodule:: matsrc
.. mat:autofunction:: matsrc.func

Online Demo

Warning

The online demo is highly outdated!

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

Note

Sphinx style markup are used to document parameters, types, returns and exceptions. There must be a blank comment line before and after the parameter descriptions.

Users

Citation

matlabdomain's People

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.