{"id":17321955,"url":"https://github.com/petercorke/help2doc","last_synced_at":"2026-03-12T10:36:59.995Z","repository":{"id":93428463,"uuid":"178769614","full_name":"petercorke/help2doc","owner":"petercorke","description":"Convert MATLAB source files to various documentation formats","archived":false,"fork":false,"pushed_at":"2020-02-10T22:04:01.000Z","size":52,"stargazers_count":5,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-21T16:32:47.593Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petercorke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-01T02:16:08.000Z","updated_at":"2025-03-23T22:41:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"3798a850-7067-4e38-b7fb-e7f3ded9717f","html_url":"https://github.com/petercorke/help2doc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/petercorke/help2doc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petercorke%2Fhelp2doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petercorke%2Fhelp2doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petercorke%2Fhelp2doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petercorke%2Fhelp2doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petercorke","download_url":"https://codeload.github.com/petercorke/help2doc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petercorke%2Fhelp2doc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271628166,"owners_count":24792821,"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","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-10-15T13:40:28.231Z","updated_at":"2026-03-12T10:36:54.962Z","avatar_url":"https://github.com/petercorke.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"This package provides some tools to support a simple MATLAB markup that is subtle enough to ensure that the help documentation is still readable using the command line `help` function. All documentation is kept with the code in a single text file which means that many software development tools (like sed, awk, diff) can be applied and revisions tracked easily using GitHub.\n\nIn contrast, MATLAB _Live Functions_ are zip files that contain many files are not easy to edit or compare outside of the MATLAB environment.\n\nThere are two tools in this package:\n\n* [help2doc](#help2doc)\n* [showtags](#showtags)\n\n# help2doc\n\nProcess MATLAB source files (functions and class definitions) and produce LaTex, HTML or MarkDown documentation.\n\n\n## Usage\n\n```\nhelp2doc options \u003clist of m files\u003e\n```\n\nThe options are:\n\n| Switch           |    Purpose |\n--- | ---\n-h, --help            | show this help message and exit\n-w, --web             | format pages for online web viewing\n-M, --doc             | format pages for matlab help browser\n-l, --latex           | format pages for creation with LaTeX\n-m, --markdown        | format pages for creation with MarkDown\n--mvtb                | format pages for MVTB\n--rtb                 | format pages for RTB\n-p PATH, --path=PATH  | path to toolbox root\n--include             | LaTeX document is for inclusion, not standalone (no preamble)\n-c, --code            | create html form of code\n-d, --display         | display in web browser\n-v, --verbose         | display in web browser\n--exclude=EXCLUDE_FILES | exclude files\n--index               | create index files\n\n\n## MATLAB markup\n\n\n### Placing the markup comment blocks\n\n### H1 line\nThe H1 line is the first line in the file and gives the function name and a brief synopsis.\n\n```matlab\n%PLOT_RIBBON Draw a wide curved 3D arrow\n```\n\n### Additional comments\nFollowing the H1 line, but in the same comment block, describe the function (or the class).\n\n```matlab\n%PLOT_RIBBON Draw a wide curved 3D arrow\n%\n% plot_ribbon() adds a 3D curved arrow \"ribbon\" to the current plot.  The ribbon by\n% default is about the z-axis at the origin.\n%\n% Options::\n% 'radius',R     radius of the ribbon (default 0.25)\n% 'N',N          number of points along the ribbon (default 100)\n%\n% 'd',D          ratio of shaft length to total  (default 0.9)\n% 'w1',W         width of shaft (default 0.2)\n% 'w2',W         width of head (default 0.4)\n% 'phi',P        length of ribbon as fraction of circle (default 0.8)\n% 'phase',P      rotate the arrow about its axis (radians, default 0)\n%\n% 'color',C      color as MATLAB ColorSpec (default 'r')\n% 'specular',S   specularity of surface (default 0.2)\n% 'diffuse',D    diffusivity of surface (default 0.8)\n%\n% 'nice'         adjust the phase for nicely phased arrow \n```\n\nDocumentation ends at the first non-comment line in the file.\n\n### Class methods\n\nIn addition to the comment block starting at the top of the file which describes the class, document each method by a comment block below the function declaration for the method.  \n\n```matlab\n       function t = SE3(obj)\n            %SE2.SE3 Lift to 3D\n            %\n            % Q = P.SE3() is an SE3 object formed by lifting the rigid-body motion\n            % described by the SE2 object P from 2D to 3D.  The rotation is about the\n            % z-axis, and the translation is within the xy-plane.\n            %\n            % See also SE3.\n```\n\nMethods for the class are listed alphabetically, except for the constructor which is always listed first.  The class name is highlighted.\n\n### Markup format\n\n#### Headings\n\nA heading is indicated by a double colon on the end of a standalone text line\n\n```matlab\n%\n% A heading::\n%\n```\n\n#### Paragraph\n\nA sequence of lines with the same indent and no blank lines in between.  The first part of the paragraph is parsed to find any MATLAB code and any variables are added to a symbol table for this M-file.  Any instances of that symbol in later text are escaped in an output format specific way.\n\n```matlab\n%\n% X = FUNC(A,B) returns a matrix that is a function of A and B.  If A is a matrix then so is X.\n%\n```\nwill result in:\n\n`X = FUNC(A,B)` returns a matrix that is a function of `A` and `B`.  If `A` is a matrix then so is `X`.\n\nThe MATLAB code parser is implemented using regexp and supports the following patterns:\n```\nVLIST := VAR | VAR, \u003cVLIST\u003e | \u003cEMPTY\u003e | ...\nLHS := F | F(\u003cVLIST\u003e) | OBJ.METHOD | OBJ.METHOD(\u003cVLIST\u003e)\nRHS := VAR | [\u003cVLIST\u003e]\nEXPR := \u003cLHS\u003e | \u003cRHS\u003e = \u003cLHS\u003e\n```\n\n\n#### Lists\nA list item begins with a hyphen.\n```matlab\n%\n% - First list item.\n% - Second list item.\n% - Very long list item which wraps\n%   around to the next line.\n%\n```\nLists may also be indented.\n```matlab\n%\n% - First list item.\n%   - First line of indented list\n%   - Second line of indented list\n% - Second line of original list\n%\n```\n\n#### Table\nOnly two column tables are supported.  The columns are separated by at least 3 white spaces.\n```matlab\n%\n% A    first row\n% B    second row\n% AA   third row\n% BB   very long table text which wraps\n%      around to the next line.\n%\n```\nTables cannot be nested.  There is no header row.\n\nIn MarkDown output format it is mandatory to have a header row, so the first row of a table is empty.\n\n#### Literal\n\nAny code that is indented by at least 8 blanks is treated as a literal\n\n```matlab\n%          for i=1:100\n%             do_a_thing();\n%          end\n```\n\n#### See also\n\nA comma separated list of functions is transformed into hyperlinked text.\n\n```matlab\n% See also function1, function2, function3.\n```\n\n## Tags and indices\n\nIf the `--index` command option is given, then indices are compiled and extra output files are created.\n\nA comment line like\n\n```matlab\n%## tag1 tag2 ...\n```\nwill cause the containing file to be added to various indices:\n\n* the alphabetic index called `index_alpha` with an extension that depends on the output language.\n* one or more per tag index files with names of the form `index_tag` with an extension that depends on the output language.\n\n# showtags\nA command line utility that will show a formatted list of all functions and their tags, for example\n\n```matlab\n% showtags *m\n           t2r.m: 2d 3d homogeneous\n   tb_optparse.m: utility\n     tr2angvec.m: 3d homogeneous rotation\n      tr2delta.m: 3d differential homogeneous\n        tr2eul.m: 3d homogeneous rotation\n        tr2jac.m: 3d differential homogeneous\n        tr2rpy.m: 3d homogeneous rotation\n         tr2rt.m: 2d 3d homogeneous rotation translation\n```\n\nThe tags are listed alphabetically, and unknown tags are displayed inside angle brackets.\n\n# TODO\n\n* `--rtb` and `--mvtb` add specific footer and copyright notices to the output documentation.  This needs to be generalized.\n* the MATLAB file parser still needs work\n* I think the HTML output generator is broken now...\n* Need to handle tags for classes\n* Need to create index generator code for other languages than MarkDown\n* Probably need to split `GenText.py` into per language files, it's too big\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetercorke%2Fhelp2doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetercorke%2Fhelp2doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetercorke%2Fhelp2doc/lists"}