{"id":18143275,"url":"https://github.com/sphinx-contrib/matlabdomain","last_synced_at":"2025-04-09T07:00:23.535Z","repository":{"id":25745634,"uuid":"105161090","full_name":"sphinx-contrib/matlabdomain","owner":"sphinx-contrib","description":"A Sphinx extension for documenting Matlab code","archived":false,"fork":false,"pushed_at":"2024-10-20T07:38:37.000Z","size":956,"stargazers_count":78,"open_issues_count":26,"forks_count":46,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-02T05:02:45.996Z","etag":null,"topics":["matlab","python","sphinx","sphinx-extension","sphinxcontrib"],"latest_commit_sha":null,"homepage":"http://sphinxcontrib-matlabdomain.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sphinx-contrib.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-28T14:48:43.000Z","updated_at":"2025-03-29T18:03:59.000Z","dependencies_parsed_at":"2023-12-10T11:23:52.433Z","dependency_job_id":"c88e265a-644b-4c69-ace9-5d07004502e5","html_url":"https://github.com/sphinx-contrib/matlabdomain","commit_stats":{"total_commits":281,"total_committers":24,"mean_commits":"11.708333333333334","dds":0.395017793594306,"last_synced_commit":"9e345112a4a0d4a3dcd09689038250395811cd27"},"previous_names":[],"tags_count":79,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Fmatlabdomain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Fmatlabdomain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Fmatlabdomain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Fmatlabdomain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sphinx-contrib","download_url":"https://codeload.github.com/sphinx-contrib/matlabdomain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994118,"owners_count":21030050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["matlab","python","sphinx","sphinx-extension","sphinxcontrib"],"created_at":"2024-11-01T19:06:20.898Z","updated_at":"2025-04-09T07:00:23.487Z","avatar_url":"https://github.com/sphinx-contrib.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\r\n.. |github-action-badge| image:: https://github.com/sphinx-contrib/matlabdomain/actions/workflows/python-package.yml/badge.svg\r\n   :align: middle\r\n\r\n.. |rtd-badge| image:: https://readthedocs.org/projects/sphinxcontrib-matlabdomain/badge/?version=latest\r\n   :target: https://sphinxcontrib-matlabdomain.readthedocs.io/en/latest/?badge=latest\r\n   :alt: Documentation Status\r\n   :align: middle\r\n\r\n+----------------------+-----------------------+\r\n+ Github Actions       | |github-action-badge| |\r\n+----------------------+-----------------------+\r\n+ Documentation Status | |rtd-badge|           |\r\n+----------------------+-----------------------+\r\n\r\nsphinxcontrib-matlabdomain -- Sphinx domain for auto-documenting MATLAB\r\n=======================================================================\r\n\r\nThis extension provides a `Sphinx \u003chttp://www.sphinx-doc.org/en/master/index.html\u003e`_\r\n*domain* for automatically generating doumentation from MATLAB source files.\r\nIt is modelled after the `Python autodoc \u003chttp://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html\u003e`_.\r\n\r\nThe extension allows you to have your documentation and source files together\r\nand use the powerful `Sphinx \u003chttp://www.sphinx-doc.org/en/master/index.html\u003e`_\r\ndocumentation tool. All your MATLAB file help text can be automatically\r\nincluded in the your documentation and output as for instance HTML.\r\n\r\nThe extension works really well with `sphinx.ext.napoleon\r\n\u003chttps://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html\u003e`_.\r\n\r\nRecent `Changes \u003chttps://github.com/sphinx-contrib/matlabdomain/blob/master/CHANGES.rst\u003e`_.\r\n\r\n\r\nUsage\r\n=====\r\n\r\nThe Python package must be installed with::\r\n\r\n   pip install sphinxcontrib-matlabdomain\r\n\r\nIn general, the usage is the same as for documenting Python code. The package\r\nis tested with Python \u003e= 3.8 and Sphinx \u003e= 4.5.0.\r\n\r\nFor a Python 2 compatible version the package must be installed with::\r\n\r\n   pip install sphinxcontrib-matlabdomain==0.11.8\r\n\r\n\r\nConfiguration\r\n-------------\r\nIn your Sphinx ``conf.py`` file add ``sphinxcontrib.matlab`` to the list of\r\nextensions. ::\r\n\r\n   extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc']\r\n\r\nFor convenience the `primary domain \u003chttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-primary_domain\u003e`_\r\ncan be set to ``mat`` with.::\r\n\r\n   primary_domain = \"mat\"\r\n\r\n\r\nAdditional Configuration\r\n~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\n``matlab_src_dir``\r\n   In order for the Sphinx MATLAB domain to auto-document MATLAB source code,\r\n   set the config value of ``matlab_src_dir`` to an absolute path or a path\r\n   relative to the source directory. Currently only one MATLAB path can be\r\n   specified, but that folder and all the subfolders in that tree will be\r\n   searched.\r\n\r\n``matlab_short_links``\r\n   Shorten all class, package and functions to the minimum length. This assumes\r\n   that everything is in the path as we would expect it in MATLAB. This will\r\n   resemble a more MATLAB-like presentation. If it is ``True`` is forces\r\n   ``matlab_keep_package_prefix = False``. Further, it allows for much shorter\r\n   and cleaner references. Example, given a path to classes like\r\n   ``target.subfolder.ClassFoo`` and ``target.@ClassFolder.Classfolder``\r\n\r\n   * With ``False``::\r\n\r\n      :class:`target.subfolder.ClassFoo`\r\n\r\n      :class:`target.@ClassFolder.Classfolder`\r\n\r\n   * With ``True``::\r\n\r\n      :class:`ClassFoo`\r\n\r\n      :class:`ClassFolder`\r\n\r\n   Default is ``False``. *Added in Version 0.19.0*.\r\n\r\n``matlab_auto_link``\r\n   Automatically convert the names of known entities (e.g. classes, functions,\r\n   properties, methods) to links. Valid values are ``\"basic\"``\r\n   and ``\"all\"``.\r\n\r\n   * ``\"basic\"`` - Auto-links (1) known classes, functions, properties, or\r\n     methods that appear in docstring lines that begin with \"See also\" and any\r\n     subsequent lines before the next blank line (unknown names are wrapped in\r\n     double-backquotes), and (2) property and method names that appear in lists\r\n     under \"\u003cMyClass\u003e Properties:\" and \"\u003cMyClass\u003e Methods:\" headings in class\r\n     docstrings.\r\n\r\n   * ``\"all\"`` - Auto-links everything included with ``\"basic\"``, plus all known\r\n     classes and functions everywhere else they appear in any docstring, any\r\n     fully qualified (including class name) property or method names, any\r\n     names ending with \"()\" within class, property, or method docstrings that\r\n     match a method of the corresponding class, and any property or method names\r\n     in their own docstrings. Note that a non-breaking space before or after\r\n     a name will prevent auto-linking.\r\n\r\n   Default is ``None``. *Added in Version 0.20.0*.\r\n\r\n``matlab_show_property_default_value``\r\n   Show property default values in the rendered document. Default is ``False``,\r\n   which is what MathWorks does in their documentation. *Added in Version\r\n   0.16.0*.\r\n\r\n``matlab_show_property_specs``\r\n   Show property *specifiers*, the size, class and validators, in the rendered\r\n   document. Default is ``False``, which is what MathWorks does in their\r\n   documentation. *Added in Version 0.22.0*.\r\n\r\n``matlab_class_signature``\r\n   Shows the constructor argument list in the class signature if ``True``.\r\n   Default is ``False``. *Added in Version 0.20.0*.\r\n\r\n``matlab_keep_package_prefix``\r\n   Determines if the MATLAB package prefix ``+`` is displayed in the generated\r\n   documentation.  Default is ``False``.  When ``False``, packages are still\r\n   referred to in ReST using ``+pakage.+subpkg.func`` but the output will be\r\n   ``pakage.subpkg.func()``. Forced to ``False`` if  ``matlab_short_links`` is\r\n   ``True``. *Added in Version 0.11.0*.\r\n\r\n``matlab_src_encoding``\r\n   The encoding of the MATLAB files. By default, the files will be read as utf-8\r\n   and parsing errors will be replaced using ? chars. *Added in Version 0.9.0*.\r\n\r\nIf you want the closest to MATLAB documentation style, use ``matlab_short_links\r\n= True`` and ``matlab_auto_link = \"basic\"`` or ``matlab_auto_link = \"all\"`` in\r\nyour ``conf.py`` file.\r\n\r\n\r\nRoles and Directives\r\n--------------------\r\n\r\nPlease see `Sphinx Domains \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html\u003e`_ and\r\n`sphinx.ext.autodoc\r\n\u003chttp://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html\u003e`_ for\r\ndocumentation on the use of roles and directives. MATLAB code can be documented\r\nusing the following roles and directives:\r\n\r\n====================================  ===========================================\r\nDirective                             MATLAB object\r\n====================================  ===========================================\r\n``.. module:: foldername``            **folders, packages and namespaces**\r\n``.. currentmodule:: foldername``     * set folder but do not link\r\n``.. automodule:: foldername``        * auto-document\r\n``:mod:`foldername```                 * reference\r\n``.. function:: funcname``            **function definition and signature**\r\n``.. autofunction:: funcname()``      * auto-document\r\n``:func:`funcname```                  * reference\r\n``.. script:: scriptname``            **script definition**\r\n``.. autoscript:: scriptname``        * auto-document\r\n``:scpt:`scriptname```                * reference\r\n``.. class:: classname()``            **class definition and optional signature**\r\n``.. autoclass:: classname``          * auto-document\r\n``:class:`classname```                * reference\r\n``.. method:: methname()``            **method definition and signature**\r\n``.. automethod:: methname``          * auto-document\r\n``:meth:`methname```                  * reference\r\n``.. staticmethod:: statmethname()``  **static method definition and signature**\r\n``.. automethod:: statmethname``      * auto-document\r\n``:meth:`methname```                  * reference\r\n``.. attribute:: attrname``           **property definition**\r\n``.. autoattribute:: attrname``       * auto-document\r\n``:attr:`attrname```                  * reference\r\n``.. application:: appname``          **application definition**\r\n``.. autoapplication:: appname``      * auto-document\r\n``:app:`appname```                    * reference\r\n====================================  ===========================================\r\n\r\nSeveral options are available for auto-directives.\r\n\r\n* ``:members:`` auto-document public members\r\n* ``:show-inheritance:`` list bases\r\n* ``:undoc-members:`` document members without docstrings\r\n* ``:annotation:`` specifies attribute annotation instead of default\r\n\r\nThere are also several config values that can be set in ``conf.py`` that will\r\naffect auto-docementation.\r\n\r\n* ``autoclass_content`` can be set to ``class``, ``both`` or ``init``, which\r\n  determines which docstring is used for classes. The constructor docstring\r\n  is used when this is set to ``init``.\r\n* ``autodoc_member_order`` can be set to ``alphabetical``, ``groupwise`` or\r\n  ``bysource``.\r\n* ``autodoc_default_flags`` can be set to a list of options to apply. Use\r\n  the ``no-flag`` directive option to disable this config value once.\r\n\r\n.. note::\r\n\r\n    The module roles and directives create a psuedo namespace for MATLAB\r\n    objects, similar to a package. They represent the path to the folder\r\n    containing the MATLAB object. If no module is specified then Sphinx will\r\n    assume that the object is a built-in.\r\n\r\nExample: given the following MATLAB source in folder ``test_data``::\r\n\r\n    classdef MyHandleClass \u003c handle \u0026 my.super.Class\r\n        % a handle class\r\n        %\r\n        % :param x: a variable\r\n\r\n        %% some comments\r\n        properties\r\n            x % a property\r\n\r\n            % Multiple lines before a\r\n            % property can also be used\r\n            y\r\n        end\r\n        methods\r\n            function h = MyHandleClass(x)\r\n                h.x = x\r\n            end\r\n            function x = get.x(obj)\r\n            % how is this displayed?\r\n                x = obj.x\r\n            end\r\n        end\r\n        methods (Static)\r\n            function w = my_static_function(z)\r\n            % A static function in :class:`MyHandleClass`.\r\n            %\r\n            % :param z: input z\r\n            % :returns: w\r\n\r\n                w = z\r\n            end\r\n        end\r\n    end\r\n\r\nUse the following to document::\r\n\r\n    Test Data\r\n    =========\r\n    This is the test data module.\r\n\r\n    .. automodule:: test_data\r\n\r\n    :mod:`test_data` is a really cool module.\r\n\r\n    My Handle Class\r\n    ---------------\r\n    This is the handle class definition.\r\n\r\n    .. autoclass:: MyHandleClass\r\n        :show-inheritance:\r\n        :members:\r\n\r\nIn version 0.19.0 the ``.. automodule::`` directive can also take a ``.`` as\r\nargument, which allows you to document classes or functions in the root of\r\n``matlab_src_dir``.\r\n\r\n\r\nModule Index\r\n------------\r\n\r\nSince version 0.10.0 the *MATLAB Module Index* should be linked to with::\r\n\r\n   `MATLAB Module Index \u003cmat-modindex.html\u003e`_\r\n\r\nOlder versions, used the *Python Module Index*, which was linked to with::\r\n\r\n   :ref:`modindex`\r\n\r\n\r\nDocumenting Python and MATLAB sources together\r\n==============================================\r\n\r\nSince version 0.10.0 MATLAB and Python sources can be (auto-)documented in the same\r\nSphinx documentation. For this to work, do not set the `primary domain \u003chttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-primary_domain\u003e`_.\r\n\r\nInstead use the ``mat:`` prefix before the desired directives::\r\n\r\n   .. automodule:: func\r\n   .. autofunction:: func.main\r\n\r\n   .. mat:automodule:: matsrc\r\n   .. mat:autofunction:: matsrc.func\r\n\r\n\r\nOnline Demo\r\n===========\r\n\r\n.. warning::\r\n\r\n   The online demo is highly outdated!\r\n\r\nThe test docs in the repository are online here:\r\nhttp://bwanamarko.alwaysdata.net/matlabdomain/\r\n\r\n.. note::\r\n\r\n    Sphinx style markup are used to document parameters, types, returns and\r\n    exceptions. There must be a blank comment line before and after the\r\n    parameter descriptions.\r\n\r\n\r\nUsers\r\n=====\r\n\r\n* `Cantera \u003chttp://cantera.github.io/docs/sphinx/html/compiling/dependencies.html?highlight=matlabdomain\u003e`_\r\n* `CoSMo MVPA \u003chttp://cosmomvpa.org/download.html?highlight=matlabdomain#developers\u003e`_\r\n* `The Cobra Toolbox \u003chttps://opencobra.github.io/cobratoolbox/stable/index.html#\u003e`_\r\n* `The RepLAB Toolbox \u003chttps://replab.github.io/replab\u003e`_\r\n\r\n\r\nCitation\r\n========\r\n.. image:: https://zenodo.org/badge/105161090.svg\r\n   :target: https://zenodo.org/badge/latestdoi/105161090\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-contrib%2Fmatlabdomain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsphinx-contrib%2Fmatlabdomain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-contrib%2Fmatlabdomain/lists"}